Templates define the html layout for a particular page type. In a template you can mix plain html with control structures and variable interpolation. The html page is generated by evaluating the template with the appropriate evaluation context, provided by Urubu.

Templates are part of the website project setup. If you are a content contributor, you may not have to worry about them. All you have to do is specify the appropriate layout name in the YAML front matter of your content files.

In general, it is better to do programming in Python code. However, for the purpose of generation of pages in a format such as html, this is not very practical. Therefore, a template contains both html and programming constructs. Template programming is good for common tasks like the following:

  • iteration over a list of items
  • testing whether an item is defined
  • filtering items, possibly with user-defined filters
  • comparing the loop item object with the current object, to check whether it is active

Urubu interacts with templates by providing an evaluation context with the appropriate objects. The goal is to make the job of the templates as easy as possible with ready-to-use object attributes.

The template library

Urubu uses the Jinja2 templating language library.

Jinja2 has great documentation and you should check it out when using templates in Urubu.

A great feature of Jinja2 is template inheritance. With this technique, you can easily generate small variations of a parent template.


Link objects are the primary objects that you use in templates. They come in a number of flavours:

Link object Description
global link object Defined in the _site.yml file.
local link object Defined locally in the content attribute of an index file.
folder object Corresponds to a project subdirectory.
page object Corresponds to a Markdown content file.
tag folder object Dedicated folder for content ordered by tag.
tag object Represents content corresponding to a specific tag.


Link objects have attributes. The defined attributes depend on the type of the link object.

The following attributes are common to all link objects:

Attribute Description
url The url of the object.
title The title of the object.

All link objects except local link objects also have an id attribute:

Attribute Description
id The unique id by which the object is known in the project.

Folder and page objects have the following attributes:

Attribute Description
fn The pathname of the file or directory corresponding the object.
components The components of the object's pathname, without file extension, as a list.
mdate Modification date

Folder objects also have a content attribute:

Attribute Description
content The content of the folder as a list of page & folder objects.

In addition, all attributes specified in the YAML front matter of the corresponding index file will be available as attributes of the folder object.

Page objects have the following additional attributes:

Attribute Description
layout The template to render the object as a html file.
body The page content in html.
toc The table of contents of the page as an unordered html list.
breadcrumbs Breadcrumbs as a list. The current page object is at position 0, the containing folder objects are at the higher positions.
prev The previous page object in the content, or None if there is none
next The next page object in the content, or None if there is none

In addition, all attributes specified in the YAML front matter of the corresponding content file are available as attributes of the page object.

Index pages

Index pages are associated with index.md files. They are special in the sense that they define the attributes and the content of a folder. Therefore, they have the same content attribute as the corresponding folder object.

Tag objects

Tag objects are inferred by Urubu automatically. They list the content corresponding to a tag.

Attribute Description
id /tag/{{tag}}
components [tag, {{tag}}]
title tag
tag tag
layout tag
content List of page & folder objects corresponding to tag.

The tag content is ordered by date, most recent first. If the date is not defined, the modification date is used as a fallback (mdate attribute).

The layout name is predefined to tag. You have to provide the tag.html template to trigger the rendering of tag objects. In the simplest case, it may be sufficient to inherit from a general index layout.

Tag folder object

The tag folder object is a special top-level folder whose id is /tag. Urubu infers tag-related content for this folder automatically.

You can optionally create the corresponding directory in the source code, and use the index file to set attributes such as the layout. In any case, Urubu will create the object if tags are used, and infer the content attribute.

Attribute Description
id /tag
components [tag]
content A list of tag objects, inferred by Urubu.

The content is ordered according to the content size of tag objects, the largest one first.

Context variables

Urubu makes the context available to templates with two context variables.


This variable holds site-wide information.

It has one predefined attribute:

Attribute Description
reflinks A mapping from all reference ids to link objects.

Note that the id of the root object is /. Starting from there, you can traverse the whole site.

In addition, all the attributes specified in the _site.yml file will be available as attributes of the site variable.


This variable holds the current page or tag object.