taika.ext.layouts – Jinja layouts

This extension renders documents content trought a the Jinja2 templating engine. It also renders the content of documents itself if any Jinja block/comment/var is detected.

Event

This extension is subscribed to the site-post-read event.

Payload

When the content and the templates are rendered, certain payload is passed and becomes accessible by both content and templates. This payload has two main keys: site and document.

Using document you can access the document attributes being processed, such as the path, content, etc. Check Document specification for details.

Inside site, the taika.Taika is accessible.

Note

Note that site.config returns a dictionary with all the sections included, so to access which extensions are listed you should use site.config.taika.extensions. This is a long “import-like” statement, and probably we will shrink it in the future.

Frontmatter

layout(str)

The layout that should render the document. Should exist under the layouts_path. If None the documents is not passed throught the template, but its body is still rendered.

Configuration

Note

All configuration hangs from a key in the YML configuration named ‘layouts’. Inside it, you can add the following options:

path(list)

Default: [./templates/]

A list of paths from where the layouts will be loaded.

options(dict)

Default: {} (empty-dict)

A dictionary (key-value) of options to pass to the Jinja environment when created.

default(str)

Default: index.html

The default layout if the document has no layout defined.

patterns(str)

Default: [“*”]

A list of patterns to match Which files should be renderered. Default to all the files.

Default filters

link

Link against other documents inside your site using {{ '/posts/2019/my-other-post.md' | link }}. Relative links not supported, only absolute paths will be accepted.

Process

1. (pre-registering) The JinjaRenderer is initialized with the configuration. The Jinja environment is created and the templates loaded.
2. Checks if the path of the document matches layouts_pattern, if not, skips it.
3. Composes the layout using the document itself, so the document metadata is available directly.
4. If the content has any Jinja flag, it is renderered, so you can include Jinja syntax into the document text.
5. Then the content (rendered or not) is rendered throught the template layout.
6. The document’s content is modified.
7. Done!

Classes and Functions

exception DocumentNotFound

class JinjaRenderer(config)

This class holds the Jinja2 environment, removing the need to create it each time.

Attributes:

env : jinja2.Environment

The configured Jinja environment.

layouts_patterns : str

The list of patterns which will be used to decide if the document should be processed.

layouts_default : str

The option so the JinjaRenderer.render_content() can access it.

render_content(self, site)

exception RelativeLinkNotSupported

link(context, path)

setup(site)