Built-in Macros Reference
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 (first found name wins). |
Using macros in theme templates
You can use macros in templates as well, assuming that you can provide all of
their required arguments. All pages have available site
and page
variables.
Some built-in macros (like ref
) expect these to be available globally. In
these cases you can import stag.html with context:
{% from "stag.html" import ref with context %}
Available macros
figure
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" />
</figure>
ref
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) }} → https://example.com/post/foo#my-header
absref
macro absref(slug)
Same as ref(slug, abs=True)
absurl
macro absurl(slug)
Returns an absolute URL to the given resource, without validation of its
existence. slug
can point to any resource managed or not managed by stag.