By default, Urubu doesn't allow content on an index page.

Background

As mentioned on the Why Urubu? page, I find it commendable that Jan Decaluwe has designed Urubu with good navigation techniques in mind. And I would agree that having too much content on an index page risks making it hard for a user to infer the best way to navigate the website. So in this respect it makes sense that Urubu should limit the amount of content that can be displayed on an index page: in theory, a short blurb and a list of links is all you should need.

However, in practice it may be necessary to tell the user something important, something he or she will need to consider before deciding how best to navigate through your website. For example, on the index page for the pages on Urubu that you are currently reading, I wanted to give my readers (if any there be) some useful information before they read any particular page.

So it's a bit of a problem that, in the default version of Urubu—by which I mean the Urubu Quickstart site—the _layouts/index.html template doesn't write out any content appearing after the yaml front matter in an index.md file. In other words, Urubu doesn't allow content on an index page.

The Fix

The fix is easy. First, edit _layouts/index.html so that it displays the body inside a contents block, thus:

<div class="row">
    {% block content %}
        <div class="col-md-7 col-md-offset-2" role="main">
            <main>
                {{this.body}}
            </main>
        </div>
    {% endblock content %}
</div>

Next add content to the relevant index.md file, after the yaml front matter section. Here's my content for the Urubu pages.

---
One way to interpret this section of *Close to the Machine* is as a complement to the [Urubu Quickstart Guide](http://urubu-quickstart.jandecaluwe.com). These pages could be read either consecutively, or individually according to your particular interests and needs.

Unintended Consequences

When you put in the fix described above, you might find that the content on your index page "drowns out" the rest of the page. For example, when I added my contents to the Urubu page in Close to the Machine, I felt that the contents made the nature of the page—that is, a page whose primary purpose was to serve as a starting point for the navigation toward other pages—was lost.

My solution was to make the purpose of the index page overt by modifying the index.html template to give the link section of the page a "Table of Contents" title. The result is an index page with what seems to me a clean look and an unambiguous purpose, although I'm willing to admit that there may be other solutions equally as good out there.