Getting started

Installing Templar

The latest version of Templar can be installed through pip:

pip install templar

Note: Templar is currently supported only for Python3.3 and above.

You should now have access to two command-line utilities:

• templar: the primary command for Templar. We'll go over the various options throughout this document.
• markdown: a convenience command that parses Markdown using Templar's Markdown parser.

Config file

See Config API for more information about configuration

First, create a Python file that contains your Templar configurations. This config file is usually called config.py, but you can name it whatever you want as long as it has a .py extension. In our example, we'll name the config file config.py and place it in our current working directory:

vim config.py

Let's populate the file with the following content:

from templar.api.config import ConfigBuilder

config = ConfigBuilder().build()

• config.py can contain whatever you want. The only requirement is it must contain a variable called config (with a lower-case "c") that is assigned to a Config object.
• To create a Config, you should use a ConfigBuilder to incrementally build your config (using the builder pattern).

For now, we'll create a ConfigBuilder and immediately build an empty Config by calling .build(). We'll populate the ConfigBuilder in later sections.

Adding template directories

To add support for templating, we can tell Templar where it can find templates. Modify the ConfigBuilder:

from templar.api.config import ConfigBuilder

config = ConfigBuilder().add_template_dirs(
    os.path.join('blog', 'templates'),
    os.path.join('blog', 'food', 'templates')
).build()

Templar will now look in two directories to find templates (relative to the current working directory):

1. blog/templates/
2. blog/food/templates/

Templates will be searched in that order.

You can call add_template_dirs as many times as you want; the arguments you give it will be appended to the end of a list of template directories.

Adding compiler rules

Suppose we decide we want to write our content in Markdown. We can tell Templar to convert all Markdown files into HTML by modifying our ConfigBuilder:

from templar.api.config import ConfigBuilder
from templar.api.rules.compiler_rules import MarkdownToHtmlRule

config = ConfigBuilder().add_template_dirs(
    os.path.join('blog', 'templates'),
    os.path.join('blog', 'food', 'templates')
).append_compiler_rules(
    MarkdownToHtmlRule()
).build()

The MarkdownToHtmlRule tells Templar: "If the source file ends in '.md' and the destination file ends in '.html', convert the source content from Markdown into HTML."

MarkdownToHtmlRule uses Templar's built-in Markdown parser, but you can create your own compiler rule to use a different Markdown parser (or a different parser altogether, like for ReST, LaTeX, etc.). See Rules for more details.

Writing content

Before we create a template, let's create some content. For our example, we'll write a recipe in Markdown:

vim blog/food/pumpkin-pie.md

with the following contents:

~ title: Pumpkin Pie

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

This file contains standard Markdown, except for the first line ~ title: .... This is a variable declaration, which has the following syntax:

~ variable: value

Variables can be referenced from within templates (explained later) 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

Basic templating

See Templates for more information on templating

Once we are done with the Markdown file, let's create a template. Recall that, in our config.py file, we listed blog/food/templates as one of our template directories. Let's create the directory first:

mkdir -p blog/food/templates

Now we can create a template file. Add a template file called recipe.html to the templates directory:

<html>
  <head>
    <title>{{ title }}</title>
  </head>
  <body>
    <h1>{{ title }}</h1>
    <p>Author: Jane Smith</p>

    {{ blocks['all'] }}
  </body>
</html>

Templar uses Jinja2 as its templating engine, so you can refer to Jinja's documentation for a full set of features.

However, this template demonstrates two Templar-specific features:

• Variables ({{ title }}): variables can be defined in either the content file (as seen above in pumpkin-pie.md) or in the config file (see Config API for details).

• Blocks ({{ blocks['all'] }}): a block is a section of the content file. Blocks defined in source content can be accessed in templates by referencing a dictionary called blocks.

  Templar reserves the special block name "all" to mean the entire content file. In this case, we are replacing {{ blocks['all'] }} with all of the contents of pumpkin-pie.md file.

Publishing content

To publish the content, use the following command:

templar -c config.py -s pumpkin-pie.md -t recipe.html -d result.html

• -c config.py tells Templar our config file is config.py. Note: if your config file is called config.py and is in the current working directory, you can omit this part.
• -s pumpkin-pie.md specifies the source content. This flag is optional (Templar allows templating without use of a source file; this is useful if you still want to take advantage of template inheritance for static pages).
• -t template.html is the template that we are using. This flag is also optional (if no template is specified, the result will just be the contents of the file, after all Rules have been applied to it).
• -d result.html tells Templar to write the result to a file called result.html. This option is optional —- if omitted, Templar will print the result to stdout.

That's it! There should now be a file in the current working directory called result.html that contains the following:

<html>
  <head>
    <title>Pumpkin Pie</title>
  </head>
  <body>
    <h1>Pumpkin Pie</h1>
    <p>Author: Jane Smith</p>

    <p>This is a recipe for making <strong>pumpkin pie</strong>.</p>
  </body>
</html>