askama_fmt

A formatter for Askama HTML templates.

Formats .askama.html template files using the same compress → expand → indent → condense pipeline as djLint, with first-class support for Askama's Rust-specific template syntax:

• {% match %}
• {% when %}
• {% call macro() %}
• {% if let %}
• {% let %}
• else if chains

Install

cargo install askama_fmt

Or from source:

git clone https://github.com/nilswloewen/askama_fmt
cd askama_fmt
cargo install --path .

Usage

# Format all .askama.html files in a directory (recursive)
askama_fmt templates/

# Format using a glob pattern — any extension is accepted
askama_fmt "src/**/*.askama.html"
askama_fmt "src/**/*.html"

# Format a single file — any extension is accepted
askama_fmt src/templates/user.html

# Check without writing (exits 1 if any file would change — useful in CI)
askama_fmt --check templates/

When given a directory, only *.askama.html files are discovered. When given a file path or glob, any extension is formatted.

Config is read from the nearest askama_fmt.toml found by walking up from the target file's directory. CLI flags override config file values.

Config

Drop an askama_fmt.toml at your project root (or anywhere in the directory tree):

indent = 4
max_line_length = 120
max_attribute_length = 70

All Askama template syntax is handled automatically — no extra configuration needed. {% match %}/{% when %}, {% call %}, {% if let %}, {% let %}, and else if chains just work.

{% match user.role %}
    {% when Role::Admin %}
        <p>Admin panel</p>
    {% when Role::User %}
        <p>Dashboard</p>
{% endmatch %}

See askama_fmt.toml for the full default config with all options documented.

Options

CLI reference

askama_fmt [OPTIONS] [SRC]...

Arguments:
  [SRC]...  Files, directories, or glob patterns to format (targets *.askama.html)

Options:
      --stdin-filepath <PATH>          Read from stdin, write to stdout (PATH used for config discovery only)
      --check                          Exit 1 if any file would change, don't write
      --diff                           Print a unified diff for each file that would change, exit 1 if any
      --indent <N>                     Spaces per indentation level
      --max-line-length <N>            Maximum line length
      --config <PATH>                  Explicit path to askama_fmt.toml
  -h, --help
  -V, --version

Editor integration

Any editor that supports external formatters via stdin/stdout works with --stdin-filepath:

# Neovim / conform.nvim
{
  "askama_fmt",
  args = { "--stdin-filepath", "$FILENAME" },
  stdin = true,
}

# Generic: pipe current buffer through the formatter
askama_fmt --stdin-filepath path/to/file.askama.html < file.askama.html

The file is not read or written — the path is used only to find the nearest askama_fmt.toml.

CI example

- name: Check template formatting
  run: askama_fmt --check "src/**/*.askama.html"

# Review what would change without failing the build
- name: Show formatting diff
  run: askama_fmt --diff "src/**/*.askama.html" || true

License

MIT — see LICENSE.

Inspired by djLint.

How it works

Five sequential passes over the source text:

1. Compress — flatten multi-line HTML opening tags to a single line
2. Expand — put each block-level HTML tag and Askama template tag on its own line
3. Clean — strip trailing whitespace and collapse excess blank lines
4. Indent — walk line-by-line, maintaining an indent level driven by opening/closing tags
5. Condense — collapse short tag pairs back to a single line if they fit within max_line_length