-
Notifications
You must be signed in to change notification settings - Fork 4
Getting started
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.
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 calledconfig
(with a lower-case "c") that is assigned to aConfig
object. - To create a
Config
, you should use aConfigBuilder
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.
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):
blog/templates/
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.
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.
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
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 inpumpkin-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 calledblocks
.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 ofpumpkin-pie.md
file.
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 isconfig.py
. Note: if your config file is calledconfig.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 allRule
s have been applied to it). -
-d result.html
tells Templar to write the result to a file calledresult.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>