This page covers diverse topics that don't really fit together.

Headings in Markdown

Urubu diverges from the official Markdown specs when it comes to headings. According to Issue #5, this is intentional. As Urubu's main author, Jan Decaluwe, puts it:

My implicit assumption is that a page should have a single h1, reserved for the title. Note that the page title is set as an attribute in the front matter. Therefore, I have set up the Markdown processor so that h2 is the base level for headers.

I realize there are other opinions, and if necessary we can consider to make this parametrizable.

Here I'm not going to debate whether or not this was a correct decision—I'm just going to clarify the differences between the expected behavior and Urubu behavior.

Markdown supports two ways to indicate headings, Setext and atx.

Setext uses equals signs and dashes (hyphens) beneath a markdown title, thus:

Expected to be <h1>, based on the equals signs
================================

Expected to be <h2>, based on the dashes
--------------------------

Since, as Jan says, h2 is the base level for headers, in Urubu the equals signs result in headings tagged as <h2>, leaving dashed headings with <h3>.

Urubu tags this with <h2>, based on the equals signs
================================

Urubu tags this with <h3>, based on the dashes
--------------------------

The atx approach to headers uses hash symbols, aka pound signs. According to the spec, the heading level corresponds to the number of hash symbols preceding the title. Because of the aforementioned changes, however, Urubu pushes these down by one, thus:

# Urubu tags this with <h2>

## Urubu tags this with <h3>

### Urubu tags this with <h4>

I love the sidebar (i.e., the table of contents, or "toc") that comes with Urubu. It's automatically generated, thus sparing me the time and tedium of creating my own sidebar for each page of the website. It also has two elements that I never bothered to implement back in the days when I wrote my own HTML: first, it uses indentation to show which topics are nested under another topic; and second, it floats to the top of the page, staying there while you scroll down. As handy as these two are, both of these benefits gave me problems that took a while to fix.

After explaining the problems and their solutions, I also tell you how to widen the sidebar—which is less of a functional problem than an aesthetic one.

Background

A second sidebar issue cropped up early in my Urubu migration. Go to the Start Page at Urubu Quickstart. Watch the sidebar as you very slowly scroll down. You should see two things. First, that the sidebar itself does not scroll smoothly: it kind of jerks suddenly as you scroll down. Second, you'll notice that when it goes through one of these sudden jumps, it crosses over the line break just below the page title.

This bugged me. A lot.

Solution

The key to the solution is in the sidebar block of the .html template. For the default version of Urubu Quickstart, look in _layouts/page.html.

{% block sidebar %}
{% if this.toc %}
<div class="col-md-3" role="complementary">
  <nav class="hidden-print hidden-xs hidden-sm">
    <!-- Adjust data-offset-top so that the sidebar moves to the top of the page after user
    has scrolled data-offset-top pixels down. -->
    <div class="sidebar" data-spy="affix" data-offset-top="134" data-offset-bottom="60">
      <div class="well">
        <a href="#"><strong>{{this.title}}</strong></a>
        {{this.toc}}
      </div>
    </div>
  </nav>
</div>
{% endif %}
{% endblock %}

Originally, data-offset-top was set to 80 pixels. Changing this to 134 gives you much better behavior. The comment in the lines above is my attempt to explain what is happening after doing a little research, including this w3schools page.

Note that the "magic number" depends on what's going on at the top of your particular page above the sidebar. 134 fixes the problem on the Urubu Quickstart page. For Close to the Machine, I had to set data-offset-top to 322.

Bug for display of <h4> and <h5>

Very soon after I started working with Urubu, I noticed that links to <h4> and <h5> headers in the table-of-contents sidebar did not find their destination as well as links to the more common headers. I worked out a CSS solution and documented it here, in this discussion of sidebar issues.

Later, however, I realized that this problem is actually a symptom of a more general problem which I call the Link Misses Bookmark Issue.

Background

Go to the Start page of the Urubu Quickstart. Begin with your browser at its widest, and note how much whitespace there is between the table of contents and the right margin of the page. Now, keeping your eyes on the table of contents entry "Install Urubu Quickstart locally," slowly narrow your browser's width. Note how prematurely the sidebar entry wraps to the next line, so that it reads like two entries--"Install Urubu Quickstart" and "locally."

I say "prematurely" because the table of contents line doesn't need to wrap. There is plenty of space to the right. I find both the whitespace and the premature wrapping visually displeasing. On the other hand, I don't think we want to eliminate the whitespace by moving the sidebar to the right—this would either leave too much whitespace alongside the page's contents, or make the contents itself too wide.

Solution

The best solution, I think, is to ever-so-slightly adjust the width of the table of contents. Just enough to eliminate the excess whitespace and prevent premature wrapping. This should involve a very simple change to your CSS.

There's a hitch, however. Because the sidebar "magically" adjusts as you scroll down the page, the fix has to be made in two places, both when the sidebar is resting just below the matter at the very top of your page, and when it moves to keep itself at the top of the page as you scroll down.

/* Stop the table of contents from getting too narrow on smaller screens. */
.sidebar {
  width: 280px;
}

/* Keep the table from getting narrow as you scroll down the page. */
@media (min-width: 992px) {
  .sidebar.affix,
  .sidebar.affix-bottom {
    width: 280px;
  }
}

Mixed-Case Directory Names Issue

Background

Suppose you're working in the Quickstart project and you decide to rename the manual directory to manualExample. Just changing the name of the folder isn't sufficient—you'll get a make error until you also change its name in more/index.md. At this point you'll get two warnings, which you can eliminate by changing its name in content.md and the (apparently deprecated) organize.md. Now you can build cleanly.

If you inspect the new _build/index.html file, you'll see your change, but with one important difference—the build has lowercased the directory name.

Before:

<li><a href="/manual/">Manual demo</a></li>

After:

<li><a href="/manualexample/">Manual demo</a></li>

The real problem here is that Urubu does this inconsistently. It seems that the build is faithful to the case of the directory name when it generates the .html files inside that directory. For example, in _build/manualExample/index.html you will find this:

    <main>
      <h4><a href="/manualExample/intro.html">Introduction</a>
      </h4>
      <p></p>
      <h4><a href="/manualExample/chapter_1.html">First Chapter</a>
      </h4>
      <p></p>
      <h4><a href="/manualExample/chapter_2.html">Second Chapter</a>
      </h4>
      <p></p>
    </div>
  </main>

On Mac, which is case-preserving but not case-sensitive, you won't notice any navigational issues. (I suspect that Windows is the same, but haven't tested this.) On Linux, which is case-sensitive, you'll find that many of your links don't work.

In my case, I encountered the problem only after I deployed my website to my host. This is not a good time to discover a new issue, with a website half-deployed.

Solution

The solution, obviously, is not to use mixed-casing in your directory names. My background is in Java development, though, where camel-casing is not only allowed, but preferred. So it may be a hard habit for me to break.

File names

We've seen how assigning a mixed-case name to a directory can cause a problem. But what about file names? In other words, will there be a problem if you give a file a mixed-case name?

The answer is, I've done some testing and cannot reproduce the problem when it concerns file names. In fact, this website abounds in mixed-case file names.