Template Functions

Below functions are additional functions available in Jinja templates (but not macros), on top of regular Jinja built-in filters, tests, and global functions.

Global Functions

sorted_pages(pages, key=None, reverse=False)

Returns a sorted copy of list of pages. By default pages are sorted lexicographically by their paths, unless reverse is set to True. Sorting criterion can be changed by passing a "date" or "lastmod" key, which then sorts pages by their data or lastmod metadata key.

Example

<ul>
{% for page in sorted_pages(site.pages, key="date") %}
  <li><a href="{{ page.relurl }}">{{ page.md.title }}</a></li>
{% endfor %}
</ul>

slugify(text, …)

Create slugs from unicode strings. Slugs are URL-friendly texts typically composed from ASCII-only characters and without whitespaces.

Stag uses python-slugify package. See its documentation for description of all parameters which slugify() accepts.

slugify() might be also used as a filter.

Example

<a href="/tags/{{ tag | lower | slugify  }}">{{ tag }}</a>

raise(msg)

Raises an exception from inside a template, with a given message, which will terminate page rendering.

Example

{% if not found  %}
  {{ raise("cannot find a page") }}
{% endif %}

tznow(msg)

Return current datetime object in a system’s timezone.

Example

{{ tznow() | strftime("%x") }}

utcnow(msg)

Return current datetime object in UTC timezone.

Example

{{ utcnow() | strftime("%x") }}

Filters

slugify(text, …)

See slugify() in Global Functions.

strftime(datetime, format)

Returns a string representing the datetime formatted according to the format specification. See strftime format codes for description of codes possible to use in format.

Example

{{ page.md.date | strftime("%B %d, %Y") }}

rfc822format(config)

Returns a datetime string in a format defined by RFC 822. It is a format used e.g. by RSS feeds.

Example

<lastBuildDate>{{ page.md.date | rfc822format }}</lastBuildDate>

<pubDate>{{ item.md.lastmod | rfc822format }}</pubDate>

pagetype(pages, *filetypes)

Returns pages which desired output type matches any of given filetypes.

Example

{% for page in (site.pages | pagetype("html", "json") %}
  {{ page.url }}
{% endfor %}

mandatory(item, msg)

Mandates existence of optional item and returns it. If item isn’t initialized, mandatory will raise an exception with provided message, which aborts page rendering.

Example

{% set page = site.find(url) | mandatory("missing page for url: {}".format(url)) %}

sortby(iterable, *attrs, reverse=False, default=None)

Sort elements by a attributes. Each attribute is a string which denotes how a a value in each item should be accessed. They can be nested, in which case each access level must be separated with a dot, for example: parent.child.grandchild. If attribute is missing in compared element, then the default is used instead.

Items are lexicographically compared against attributes in order in which they are provided, so for each item first attributes are compared first, then second ones, third ones and so on.

When reversed is True, items are sorted from the biggest element to the smallest one.

Sort is stable, which means that relative order of elements which are equal is preserved.

Example

{% for page in (site.ordinary_pages |
    sortby("md.tag", "md.category", "url", default="", reverse=True))
  {{ page.url }}
{% endfor %}