Using built-in macros

Stag ships with several built-in macros. They are available in stag.html temlpate, which must be imported as all the other ordinary macro templates.

{% from "stag.html" import ref %}

This is a link to other [page]({{ ref("my-page") }}).
stag.html is always loaded as the last template, so in case of name clash, it will be overriden.

Available macros


macro figure(src, class=None, alt="")

Returns a <figure> for an image given in a src parameter. Produced figure will have additional class and an <img> inside the produced <figure> will have additional alt-text set from the alt parameter.

{{ figure(image.jpg, class="center", alt="image of the cat"}}

<figure class="center">
    <img src="image.jpg" alt="image of the cat" />


macro ref(slug, abs=False)

Returns an URL (permalink) to the page whose URL matches the slug. ref macro will look up for the pages whose URL ends with a slug, so it’s not necessary to include the big parts of the paths.

If two files match the slug, ref will raise an exception and refuse to produce any URL. In that case it is advisable to give a bigger part of URL.

By default ref produces relative URLs in form of /part/of/url. if abs is set to True, ref will produce an absolute URL.

ref accepts slugs with identifiers (foo#id) which can be found on a page. In that case, it will add them after finding the appropriate page.

{{ ref("foo") }} → /post/foo
{{ ref("foo#my-header") }} → /post/foo#my-header
{{ ref("foo", abs=True) }} →