-
Notifications
You must be signed in to change notification settings - Fork 4
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 inblocks
. See "Blocks in source files" below.
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 Rule
s 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>