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). 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"

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", 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 behaviour, you can set whitespace to "minimize".

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

#![allow(unused)]
fn main() {
#[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.

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. 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.