Blocks

The include tag

Templar supports linking different source files together by using a special include tag:

<!--- documentA.md -->

This is content in documentA.

<include documentB.md>

The text in the line above was content from documentB

<!--- documentB.md -->

This is content in documentB.

From the command line, you can render documentA.md:

templar -s documentA.md -d result.html

This will create a file called result.html with the following contents:

This is content in documentA.

This is content in documentB.

The text in the line above was content from documentB

Blocks

You can also include a subsection of another file. To do this, you can define blocks in the included file. A block is a section of your source file and can be declared with the following syntax:

<block name-of-block>
content
here
</block name-of-block>

• A block tag must be declared on its own line. You can have text surrounding the tag (e.g. # <block name-of-block>), but all of the text on that line will be removed. This is useful if your source file is something like Python, where you don't want the block tags to prevent you from actually running the file.
• Block names must follow the block keyword with at least one space.
• Block names do not have to be valid Python identifiers; they can contain spaces, hyphens, and other special characters. The only restriction is they cannot contain newlines.
• The closing block tag must contain the exact same name as the opening block tag.
• Blocks can be nested.
• Each file can only contain one block with a given name. If two blocks are declared with the same name, an error occurs.

Including blocks

Once you have defined blocks, you can include them in other files with the include tag. Before, when we included the entire file, we simply added the path to the file. To include a specific block in the file, append :name-of-block to the end of the filepath:

<!--- documentA.md -->

This is content in documentA.

<include documentB.md:my-block>

The text in the line above was content from documentB

<!--- documentB.md -->

<block my-block>
This is content in documentB.
</block my-block>

This content won't be included, since it is outside of 'my-block'.

Notice that we only include the block my-block from documentB.md. The rendered result will contain:

This is content in documentA.

This is content in documentB.

The text in the line above was content from documentB

Using blocks in Jinja

In addition to using blocks to link source files, you can reference source file content with blocks in Jinja. Templar creates a variable called blocks that maps block names to block content:

<!-- template.html -->

{{ blocks['my-block'] }}

Note that you can only access blocks that are defined in the target source file. For example, if you use the following Templar command

templar -s documentA.md -t template.html -d result.html

you will only have access to blocks defined in documentA.md; you can't access blocks defined in documentB.md (which is linked from documentA.md.

The 'all' block

In addition to user-defined blocks, Templar reserves a block called 'all' that represents the contents of the entire file. You can include the 'all' block just like any other block:

<include documentB.md:all>

This is effectively the same as just including the file itself:

<include documentB.md>

As a result, the 'all' block is redundant in source files. However, you can use the 'all' block in Jinja templates to access the entire contents of that source file.

<!-- template.html -->

{{ blocks['all'] }}