Overview
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
Description
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. |
Attributes
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.
site
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
This variable holds the current page or tag object.