Your source content (e.g., Markdown or reStructuredText) is read and converted into HTML. After content is converted to HTML, it is passed to a template system as a variable called content. Each template system can then insert the HTML content into a template.

handroll supports multiple template systems. Templates are stored in a templates directory at the root of your site. Alternatively, if you have very simple needs, you can use a template.html file at your site’s root.

Any template used from the templates directory must be specified using front matter (see Front matter) or the default template.html will be used. This sample Markdown file uses a string template.

%YAML 1.1
title: With a different template
template: different.html
## Another heading

This is using a different string template.

String templates

Any template using the .html extension (including the default template.html) will uses Python’s built-in string templates. String templates are limited to the capabilities of the standard library, but they can support basic needs.

Jinja2 templates

Any template using the .j2 extension will use the Jinja2 template language. handroll works with Jinja’s template inheritance system and the majority of Jinja’s other features.