nanosite

documentation

template language

In site generation, .md+, .html+, .xml+ and .tmpl files are run through the template engine. These files contain regular Markdown or HTML, interspersed with template expressions, which are surrounded by double curly braces {{ }}. The template engine compiles these expressions into HTML by following the rules on this page. Each template is compiled against a context, which is a set of variables available to the template.

Call the current context context. context["key"] denotes fetching the value of variable key from context context.

fetch

basic fetch

Syntax:

{{ key }}

Semantics: Evaluates to context["key"]. Can also grab nested entries with dot syntax: {{ site.url }} evaluates to context["site"]["url"]. By default, HTML is escaped. Use triple braces to circumvent escaping, for variables containing HTML: {{{ linkToMyInstagram }}}

Examples:

macro call

Syntax:

{{ key [parameter1 ... parameterN] }}

Semantics: If context["key"] is a macro, then call it with parameters context, parameter1, ... parameterN. Parameters can be literals — 23.5, "hello" — or variable names — posts, site.url, in which case the contents of the variable will be passed to the macro. See declaring macros.

Triple braces work the same way as in basic fetch, for macros that return HTML.

Examples:

control blocks

#if

Syntax:

{{ #if key }}
  [A]
[{{ #elif key2 }}]
  [B]
...
[{{ #else }}]
  [C]
{{ #endif }}

Semantics: If context["key"] evaluates to True, then evaluate code block [A]. Otherwise, if context["key2"] evaluates to True, then evaluate block [B]. Otherwise, evaluate the next #elif condition, and so on. If none of the conditions are met, evaluate block [C]. #elif and #else clauses are optional. key can contain spaces, i.e. in the case of a macro call.

Examples:

#for

Syntax:

{{ #for x in key }}
  ...
{{ #endfor }}

Semantics: If context["key"] is a collection, then iterate through its items. (key can contain spaces, i.e. in the case of a macro call.) Run the code block for each value of x in key, where the code block can now access x as a variable.

Examples:

declarations

#macro

Syntax:

{{ #macro name [parameter1 ... parameterN] }}
  ...
{{ #endmacro }}

Semantics: Declares a macro named name that takes parameters context, parameter1, ..., parameterN, and returns the contents of the code block. In the inner code block, the parameters are bound to the values they were called with.

Typically, macros are declared in macros.py and master.tmpl.

Examples:

#define

Syntax:

{{ #define key value }}

Semantics: Declares a variable key with value value, where value can contain spaces, i.e. in the case of a macro call.

Examples:

escaping

escaping HTML

By default, everything in double curly braces {{ }} will be HTML-escaped, meaning special HTML characters will be translated into HTML unicode escape codes. This prevents things like angle brackets < > from corrupting the page.

To circumvent this, enclose your expression in triple braces {{{ }}}. This is useful for inserting HTML onto your page.

escaping curly braces

Delimiters can be escaped with a backslash, and the template compiler will ignore them. In the site generator, \{{ will output {{, and \}} will output }}.

Note that Markdown has its own backslash escaping, so in Markdown files, you will need to use double backslashes: \\{{.