Templates

Templar uses Jinja2 as its templating engine. You can take a look at the Jinja documentation for a full set of features.

Template files can be stored anywhere. You can specify which directories contain templates in the config file:

config = ConfigBuilder().add_template_dirs(
    'path/to/templates'
).build()

When looking for templates, Jinja will look for files relative to the directories specified in template_dirs. For example,

templar -s source.md -t template.html

will look for the file path/to/templates/template.html.

In addition to Jinja's features, Templar also has a couple of its own template features:

A variable can either be defined in a source file (see "Variables in source files" below) or a config file (see Config API). These variable names must be valid Python identifiers (required by Jinja).
A block that is defined within a source file can be accessed from a dictionary called blocks. All blocks defined in the source file (excluding blocks that are linked from other files) can be found in blocks. See "Blocks in source files" below.

Variables in source files

Variables can be defined in source files. Suppose we have a file with the following content:

~ title: Pumpkin Pie

This is a recipe for making **pumpkin pie**.

The first line (~ title: ...) is a variable declaration, which has the following syntax:

~ variable: value

Variables can be referenced from within templates and are useful for storing metadata about the content. Some things to note:

variable must be a valid Python identifier, containing only alphanumeric characters and underscores (i.e. [a-zA-Z0-9_]+).
value can contain any character that is not a newline. This means values can include spaces, hyphens, underscores, and colons (the first colon in the line is used as the separator)
value will be taken as is (meaning it will not be parsed for Markdown)
The variable declaration must be on exactly one line

Variables can be defined anywhere in a source file. All variable declarations will be stripped from the source before any Rules are applied.

For source-file blocks, suppose a source file has the following block:

<block example>
Some Markdown here.
</block example>

The block example can then be used in an expression like so:

<body>
  <p>Some HTML here</p>

  {{ blocks['example'] }}

</body>