Here I present some information that I consider helpful but have not found in the Urubu documentation.

I'm not complaining—the Urubu documentation is great. Better than that of any other static website generator I've looked into, and better than the documentation for even most money-making software packages you can find. But as I migrated my website to Urubu from hard-coded HTML and CSS, it took me a while to learn a thing or two. And I am a professional software developer. If there's anyone out there trying to use Urubu, and if you are a programming newbie, this page is meant especially for you.

If on the other hand you are experienced at web development, you might want to skip much of what is on this page—except for, perhaps, two undocumented features of Urubu which the Quickstart does not provide examples of. These are discussed in two separate sections of the page: "Index Page Teasers" and "Index Page Abstracts."

Note that this page is not meant to replace the Urubu documentation, only to supplement it. Here I avoid repeating anything already well documented. In fact, the same can be said of all the Urubu pages in Close to the Machine.

If you have a local copy of Urubu Quickstart, as you go through this documentation you may find it helpful to open up any files that are mentioned. If you don't have a local copy, I suggest you get one. It's easy.

Glossary

For the sake of clarity, let's define few terms that I'll be using on these pages. Experienced web designers may already be familiar with most of these, but relative beginners like myself might be unfamiliar with the vocabulary. Many are Urubu-specific, for which I try to use the same term as you find in the official documentation. But note that there are a few terms whose names I had to make up.

In these notes, I often refer to the "default" behavior; by this I mean the way the website is set up in Urubu Quickstart. (In case you haven't realized this yet, the best way to use Urubu to build your own website is by starting with the one provided by the Quickstart.)

Parts of an Urubu Page

In this section, I use the Start Page of Urubu Quickstart to illustrate the parts of a typical Urubu content page.

Start page of Urubu Quickstart
Start page of Urubu Quickstart

The one item not on the screenshot above but still worth mentioning is the footer. I put my copyright notice within the footer at the bottom of the page you're looking at right now.

Parts of an Urubu Home Page

The default Urubu home page has a number of items that are not found on a default content page.

Parts of an Urubu home page
Parts of an Urubu home page

A jumbotron is a Bootstrap component. In the screenshot above it's the dark grey rectangle between the navbar and the start button. You can see that on my own pages I have modified the jumbotron quite a bit, to the point of adding images.

The title and tagline are two of the variables that you can find in an Urubu markdown file, which we cover next.

Parts of a Markdown File

For my implementation of an Urubu website, I had to make some changes concerning various elements of a markdown (.md) file. A markdown file contains a number of parts.

Parts of an .md file
Parts of an .md file

The two main parts of a markdown file are the yaml front matter and the page content (or just content), separated by the divider.

The yaml front matter consists of variables (or keywords) and their associated values.

The page content may optionally contain a lead paragraph (or just lead), and is often separated into sections by section headings.

Markdown pages have different elements, depending on their type. In the screenshot above, you see that the layout variable has the value page. This brings us to the topic of layouts.

Urubu Layouts

In traditional websites, both the layout and the content of a page are defined in that page's .html file. Urubu and other static website generators let you separate layout and content. The content goes into a markdown file, while the layout goes into what is called an HTML template. A template file is just that: an empty page with defined "slots" into which the website generator drops whatever content you want.

In small one- or two-page websites, there is little advantage in separating the content and the layout. But as a website gets larger, the cost of violating the DRY (Don't Repeat Yourself) principle becomes greater and greater, because it grows more and more difficult to change a design element that is shared by all the pages. Separating content from design lets you make a single change in the HTML template, rather than in every page of the website.

In Urubu, your page's content goes into the content part of the .md file, and the page's design is controlled by the layout variable in the markdown's yaml front matter.

Layout Types

I have not been able to find a definitive list of layout types in the Urubu documentation. You might think I should be able to simply look in the _layouts folder of the Urubu Quickstart project, but there are other files there which are not layouts—footer.html, for example.

In this section I give a fairly detailed explanation of the types I've been able to discover on my own. I use the Urubu Quickstart project, whose directory structure is given on the right, to provide examples.

home

  • The home layout is meant for a website's home page—this is where a user should end up when Home is clicked on in either the navbar or the breadcrumbs.

  • As shown in the screenshot above, the default Urubu Quickstart home page displays just four elements: the navbar, the home page's title, its "tagline," and a Start button.

    • It gets the content of the first two from the yaml front matter of the top-level index.md file.

    • The page's layout—where exactly on the page the title and tagline are positioned, what size font they are displayed with, and so on—is controlled via the _layouts/home.html template. The template file also controls the Start button.

  • The first thing the template file does is call the _layouts/_base.html template, which controls the layout shared by all the website's pages. The page and index templates do the same.

  • The navbar on the home page is defined by the items listed under the content keyword in the home page's markdown file. Open up the top-level index.md file to see the list.

index

  • Urubu lets you group your website content into directories. The index page of any directory is the first one seen when the user navigates to the pages in that group, and it has a very simple job: to list the pages of its group, optionally with a brief description, and provide a clickable link to each one.

  • The markdown file for the index page is always named index.md, and its layout variable is always set to index.

  • An index page can be implemented either as a dropdown list or as a web page.

    • If it's implemented as a dropdown list, the list itself contains the group's separate pages. See this in action by clicking on the More button at the top right-hand side of the Quickstart Project.

    • If it's implemented as a web page, the group's separate pages are listed on the page. See both the Blog and the Manual pages. (Their links are in the More dropdown list.)

  • In the Quickstart project, the only way to navigate to an index page is via the More button on the right-hand side of the navbar. This is an accident and not an Urubu requirement. You can always let your users navigate to your index pages via the "normal" left-hand side navbar buttons.

  • The yaml front matter of an index markdown file can optionally list all the pages belonging to that group under the content keyword.

    • If it does list them, Urubu uses the same order when it lists the pages of that group. See manual/index.md for an example.

    • If the markdown file doesn't list them, Urubu will discover the pages on its own by looking at the files in the same directory as the index.md file. See blog/index.md for an example.

      • Notice that on this markdown page there is no content keyword.

      • Notice also that the page uses the order and reverse variables, which, in combination with the date keyword on the other pages in the blog directory, tell Urubu to list the pages in reverse chronological order. If these keywords were not used, Urubu would list the pages in that directory in alphabetical order.

  • Take a look at the index template file in _layouts/index.html. There are two main parts: the jumbotron section comes first, followed by the formatting for the list of pages. Here is the second section, where you can see the jinja2 code iterating through the content. 

    <div class="container">
      <div class="row">
        <div class="col-md-7 col-md-offset-2" role="main">
        <main>
          {% for item in this.content %}
          <h4><a href="{{item.url}}">{{item.title}}</a>
            {% if item.date|d %}
            <small>{{item.date|dateformat}}</small></h4>
            {% endif %}
          </h4>
          <p>{{item.teaser}}</p>
          {% endfor %}
        </div>
      </main>
      </div>
    </div>

  • Some notes on the index template:

    • An index page list almost appears to be centered on the page. You can see this in the _layouts/index.html template, with the use of col-md-offset-2, which moves the content two columns to the right.

    • In the listing above, notice the display of item.teaser just after page title and date. I discuss the teaser in a separate section below.

page

  • Although the description of the index layout, above, is fairly long and complicated, you'll be spending little time working on index pages. Most of your time will be spent on the content of your web pages—that is, on markdown pages whose layout variable is set to page.

  • The template for the page layout is _layouts/page.html.

    • Open this file and you'll see that it calls _base.html at the top and footer.html at the bottom.

    • You'll also see that there's a block toward the end where it implements the sidebar. (For more on the sidebar, see Sidebar Issues and Build Your Own Sidebar.)

    • Finally, toward the end of the file, you see that it calls the footer layout with the include statement.

  • The code below shows the manual/intro.md file of the default Urubu Quickstart project. If you haven't already, see how this is displayed by clicking on the More button at the top right-hand side of the Quickstart Project and selecting Manual.

---
title: Introduction 
layout: page 
pager: true
---

First paragraph.

Second paragraph.

  • pager: Sometimes it makes sense for the user to follow website pages in a pre-specified order; other times, one page is for the most part unrelated to its neighbors in the same directory and the user could read them in any order. The Quickstart project offers examples of both these approaches, with the Manual and the Blog topics.

    • If you want the user to be able to easily navigate from the bottom of one page to the top of the next, use the pager keyword in the markdown file. This puts links at the bottom of the page, allowing "Next Page" and "Previous Page" navigation. You see that the pages in the manual directory have this variable set to true, while the pages in the blog directory do not even contain this keyword.

    • When pager is set to true, Urubu "learns" the order of your pages from the way they are listed under the content variable in the index.md file belonging to that directory. See, for example, manual/index.md.

simple_page

  • Use the simple_page layout when you don't want the sidebar.

  • Open _layouts/simple_page.html to see it contains just three lines: 

{% extends "page.html" %}

{% block sidebar %}
{% endblock %}

  • The template begins by using the Jinja2 extends tag to declare that this template extends page.html. This tells Urubu to use the code in page.html, with the exception of any blocks defined in the current file.

    • One block is defined in the current file—the sidebar block.

    • So, in generating the html for any page whose layout is simple_page, Urubu will do whatever it does for pages whose layout is page except that, when it reaches the sidebar block in the page template, it will substitute the sidebar block of this template.

    • In this case, the sidebar block is empty. Thus we have the result that no sidebar will be created.

rolling your own

  • The "Layouts" section of the Advanced page of the Quickstart manual says that you can create your own layouts. This is a valid option if you need new functionality yet hesitate to modify default behavior. I haven't explored this, but it seems to me that the approach would be to:

    • Create a name for your layout type. Let's call it "newLayout".

    • In a markdown file, set the layout variable to newLayout. (If you try to build at this point my guess is you'll get an error.)

    • Specify the design (the layout) of your new layout type in a file in _layouts/newLayout.html.

Index Page Teasers

In the section on the index layout, above, I briefly mention the teaser and list the index template code where it is displayed. There's no example in the Quickstart project of a "teaser" being displayed on an index page just beneath the page titles and dates. To see this in action, you have to modify the markdown of a normal page file, not an index page.

To see the teaser in action, add a teaser variable to manual/intro.md file, thus:

---
title: Introduction 
layout: page 
pager: true
teaser: Providing a two-paragraph introduction to this manual. 
---

Now after you run make and reload the Manual index page in your browser, you'll see your teaser displayed just below the title "Introduction." This is very useful functionality: I believe that a brief blurb explaining each page's contents can often improve an index page's usability.

Index Page Abstracts

Urubu uses the abstract keyword or variable in the template for its index pages, _layouts/index.html:

<div class="col-md-8 col-md-offset-2 text-center">
    <h1>{{this.title}}</h1>
    <p>{{this.abstract}}</p>
</div>

What's a little confusing is that no index page in Urubu Quickstart has a value for the abstract keyword in its index.md file, so you can't see this behavior in action.

So let's do this for the manual/index.md file. First add the abstract variable to the front matter, and then set its value to "Here's an example of how a manual could be presented with Urubu."

---
title: Manual demo 
layout: index
content:
    - intro 
    - chapter_1 
    - chapter_2 
abstract: Here's an example of how a manual could be presented with Urubu.
---

Here's what the page looks like after the build.

Manual page with abstract
Manual page with abstract