Templates

Stag uses Jinja Template Engine to create files from the output produced by generators.

It is configured in [template] table. Most important setting is name, which is a path to the directory from which templates will be read. Other important sub-table is [template.templates], which contains settings for default templates used for certain types of pages.

Template Name Deduction

To produce a page, Stag needs to know which template should be used from the available ones. Typically, types of pages are:

  • page for ordinary page;

  • index for start pages;

  • taxonomy for pages which hold a list of taxonomy terms;

  • list for pages which hold a list of other pages.

The following procedure is used to determine pages' type:

  1. if page sets its metadata.type field, it is used as a type,

  2. otherwise, if page is a taxonomy page, its type will be set to template.templates.taxonomy (by default: taxonomy),

  3. otherwise, if page is a list page, its type will be set to template.templates.list (by default: list),

  4. otherwise, page’s type wyll be set to template.templates.page (by default: page).

To produce the full name of the template, page type will be then combined with the output type (usually an extension typical for the kind of output produced by the generator plugin, e.g. html or xml).

There might be a situation when deduced template isn’t available. In such case, Stag provides a very basic built-in template and informs users about the situation with appropriate error prints.

Example 1. Template deduction with user-defined type

Suppose the following Markdown page:

+++
title = ""
type = "mypage"
+++

This page will use mypage.html template, because the output of Markdown rendering is html file and the type selected by the user for this page is "mypage".

Example 2. Template deduction without user-defined type

Consider the following Markdown page:

+++
title = ""
+++

Here theme must deduce the name, because there’s no one provided by the user. It is an ordinary page, so it will be taken from template.templates.page. If this setting wasn’t changed, the template which will be rendered from page.html.

Example 3. Name clash?

Consider the following Markdown page:

+++
title = ""
type = "taxonomy"
+++

and the following configuration:

[template.templates]
taxonomy = "somethingelse"

The output page will be rendered from taxonomy.html, not from somethingelse.html, because the type keyword in metadata directly maps to the name of the used template, not to the default value from config.toml.

Cache

Generating sites with a lot of web pages and a lot of plugins can sometimes become slow. To fight this, Stag caches the results of page generation and uses them when it detects that source pages haven’t changed since last run.

You can disable this behaviour and force full rebuilds by passing --no-cache option to build and serve commands. You can also make it persistent by placing no_cache = true in config.toml.

The default directory used for cache is a hidden .cache directory placed in your site’s root. You can change it by changing cache parameter in config.toml, for example:

config.toml
cache = "~/.cache/mysite"
Note
 Because almost everything in Stag is a plugin, caching is the most efficient if you use plugins which are aware of it. All built-in plugins use cached results whenever it’s possible. To learn how to make your plugins cache-friendly, refer to Plugins Programmer Manual.