Configuration

At compile time, Askama will read optional configuration values from askama.toml in the crate root (the directory where Cargo.toml can be found) if the config feature is enabled (it’s enabled by default). Currently, this covers the directories to search for templates, custom syntax configuration and escaper configuration.

This example file demonstrates the default configuration:

[general]
# Directories to search for templates, relative to the crate root.
dirs = ["templates"]
# Unless you add a `-` in a block, whitespace characters won't be trimmed.
whitespace = "preserve"

Please note that dirs support glob (*) syntax. So you can write:

[general]
dirs = ["templates/*"]

Or even:

[general]
dirs = ["templates/**"]

If you want to include sub-folders.

Whitespace control

In the default configuration, you can use the - operator to indicate that whitespace should be suppressed before or after a block. For example:

<div>


{%- if something %}
Hello
{% endif %}

In the template above, only the whitespace between <div> and {%- will be suppressed. If you set whitespace to "suppress":

[general]
whitespace = "suppress"

Then whitespace characters before and after each block will be suppressed by default. To preserve the whitespace characters, you can use the + operator:

{% if something +%}
Hello
{%+ endif %}

In this example, Hello will be surrounded with newline characters.

There is a third possibility: in case you want to suppress all whitespace characters except one, you can use ~:

{% if something ~%}
Hello
{%~ endif %}

To be noted, if one of the trimmed characters is a newline, then the only character remaining will be a newline.

If you want this to be the default behavior, you can set whitespace to "minimize":

[general]
whitespace = "minimize"

To be noted: you can also configure whitespace directly into the template derive proc macro:

#[derive(Template)]
#[template(whitespace = "suppress")]
pub struct SomeTemplate;

If you configure whitespace directly into the template derive proc-macro, it will take precedence over the one in your configuration file. So in this case, if you already set whitespace = "minimize" into your configuration file, it will be replaced by suppress for this template.

Custom syntaxes

Here is an example that defines two custom syntaxes:

[general]
default_syntax = "foo"

[[syntax]]
name = "foo"
block_start = "%{"
comment_start = "#{"
expr_end = "^^"

[[syntax]]
name = "bar"
block_start = "%%"
block_end = "%%"
comment_start = "%#"
expr_start = "%{"

A syntax block consists of at least the attribute name which uniquely names this syntax in the project.

The following keys can currently be used to customize template syntax:

• block_start, defaults to {%
• block_end, defaults to %}
• comment_start, defaults to {#
• comment_end, defaults to #}
• expr_start, defaults to {{
• expr_end, defaults to }}

Values must be at least two characters long. If a key is omitted, the value from the default syntax is used.

Escapers

Here is an example of a custom escaper:

[[escaper]]
path = "::tex_escape::Tex"
extensions = ["tex"]

An escaper block consists of the attributes path and extensions. path contains a Rust identifier that must be in scope for templates using this escaper. This type must implement the Escaper trait.

extensions defines a list of file extensions that will trigger the use of that escaper. Extensions are matched in order, starting with the first escaper configured and ending with the default escapers for HTML (extensions html, htm, xml, j2, jinja, jinja2) and plain text (no escaping; md, yml, none, txt, and the empty string). Note that this means you can also define other escapers that match different extensions to the same escaper.

You can then use templates with this extension or use the escape filter with the name of your extension in your template:

{{ some_string|escape("tex") }}

As an example, we want .js files to be treated like “txt” files. To do so:

[[escaper]]
path = "askama::filters::Text"
extensions = ["js"]

Text implements the Escaper trait so since we don’t need want any escaping on our .js files, we use it.

You can take a look at the custom escaper example in the askama repository.