Plugin List

File Type Plugins

adoc (Asciidoc)

Plugin responsible for reading Asciidoc files. Stag uses Asciidoctor for reading files. Metadata is read from ordinary Asciidoc’s metadata fields. These fields are preserved and added to the content passed to asciidoctor command.

Warning

adoc plugin extends ordinary Asciidoc’s metadata values, which typically are simple strings, to support a list of strings, which is necessary for some metadata fields (e.g. taxonomies). You may put a comma-separated list of strings inside [ and ] brackets and adoc plugin will treat it as a list of strings. If you need to use a comma inside a single value, you may escape it with backslash \ character or you may wrap it with double quotes:

:tags: [first, second, "complex, and, scary"]

Supports Table of Contents. Table of contents is available in templates separately from the ordinary content through {{ page.toc.content }}.

Plugin supports macros.

Example Asciidoc file
= My First Stag Page!
:date: 2021-09-02
:lastmod: 2021-10-01
:tags: site, something else

This was a *triumph*!

md (Markdown)

Markdown plugin reads Markdown files, which can have optional front matter with metadata, which is also saved by the reader. Front matter is expected to be in TOML format, delimited with + (3 plus signs) from the top and bottom.

Example Markdown file with front matter
+++
title = "My First Stag Page!"
date = 2021-09-02
lastmod = 2021-10-01
tags = ["site", "something else"]
+++
This was a **triumph**!

Markdown generator takes input provided by the Markdown reader and generates HTML data from it. It uses Python Markdown package. Its extensions are enabled through plugins.markdown.extensions list.

Configuration is stored inside plugins.markdown table in config.toml.

Example markdown configuration
[plugins.markdown]
extensions = ["sane_list", "smarty", "footnotes", "toc"]

Supports Table of Contents via python-markdown toc extension. Table of contents is available in templates separately from the ordinary content through {{ page.toc.content }}.

Plugin supports macros.

raw_markup (XML, JSON etc.)

Plugin which copies files from the content directory to _output. Currently the following file types are supported: XML, JSON, TOML, YAML.

Plugin supports reading front matter with metadata from input files. Contents of front matter are not copied. On top of that, raw_markup plugin sets the following default metadata, if it isn’t provided in the front matter:

  • title is set to capitalized file name (i.e. first capital letter, other ones lower case);

  • type to the stem of the file, i.e. to the file name without its extension (for example: rss.xml will have rss type);

  • date - to date and time of parsing.

Plugin supports macros.

JSON with front matter example
+++
title = "My Extraordinary JSON file"
++++
{
  "foo": "bar"
}

Other Plugins

macros

Macros provides input postprocessing. Thanks to it you can use Jinja macros inside input files (e.g. in Markdown). It enables a system which resembles "shortcodes" known from other static site generators.

To enable macros you must configure path to the directory which contains Jinja templates with macros definitions. Macros use [plugins.macros] table in config.toml to do that.

Example macros configuration
[plugins.macros]
path = "directory/with/macros"

Because macros plugin internally mutates the page input, file type plugins should be prepared for it by splitting reading input and generating output to two different stages, for example:

def register_plugin(site):
    site.signals.page_added.connect(read)
    site.signals.processors_init.connect(generate)

See also Custom Macros which explains in detail how to add new macros

Example of file which use a macro
+++
title = "My Page"
++++

{% from "macros.html" import mymacro %}

Ordinary content {{ mymacro(foo="bar") }} rest of ordinary content.

taxonomies

Taxonomies are automatically generated collections of pages (e.g. tags or categories). They must be enabled in config.toml and are generated from metadata of content files.

Enabling 2 taxonomies in config.toml
[[taxonomies]]
key = "tags"
singular = "tag"
plural = "tags"

[[taxonomies]]
key = "category"
plural = "categories"

Once defined, stag scans metadata of files and groups files which have the same metadata:

Setting terms of taxonomy on a page
tags = ["foo", "bar"]
category = "my category"

Each taxonomy generates a taxonomy landing page and a list of term pages. (think of tags/foo, tags/bar etc.):

Taxonomy Landing Page

it contains data regarding taxonomy itself and a list of term pages, which can be accessed from page.taxonomy.terms.

Term Pages

each of them contains a list of ordinary pages, which belong to the term (e.g. which have a specific tag); they can be accessed from page.term.pages. Additionaly they have metadata['taxonomy'] set with a name of parent taxonomy.

Rendering taxonomies

Taxonomies are rendered like the ordinary pages (see Template name deduction, but they use different default templates. Landing taxonomy pages use taxonomy template (e.g. taxonomy.html) and term pages use list template (e.g. list.html). This can be customised in two ways:

  1. Default templates for all taxonomy/term pages can be changed in [template.templates] section.

    Setting different default templates for taxonomy page and terms pages
    [template.templates]
taxonomy = "mytaxonomy"
list = "mylist"

  2. If stag finds a file which would result with the same URL as taxonomy or term page, it incorporates it instead of throwing a usual error:

    1. Metadata of the file is preserved, but missing entries necessary for taxonomies are created: this can be used to pass custom metadata to Jinja and template. For example type can be explicitly set, which will result in choosing a different template.

    2. File content is preserved.

    3. page lists and taxonomy data is added to the page object and overrides any previous entries.

      For example, to add a metadata to the "tags" taxomony, create a file tags.md or tags/index.md inside your content, with the following content:

      Page for taxonomy landing page (tags.md)
      ++++
title = "List of tags"
mymetadata = "My Metadata"
++++
      Page for a single tag (tags/mytag.md)
      ++++
title = "Special case of mytag"
mytagmetadata = "special metadata"
++++