Askama (Rust Templating)
Load before writing or reviewing an askama template ({{ .. }} / {% .. %} files under templates/) or Rust code that derives askama::Template.
Askama is a compile-time, Jinja-like template engine for Rust: templates are parsed at build time and generate type-checked Rust code. Rules hold for the unified askama crate, version 0.16.x (MSRV 1.88); a rule tagged with a version does not apply to an older askama pinned in Cargo.toml.
Captured 2026-11-11 (askama 0.16.1). To update: re-verify against the askama book + docs.rs/askama.
1. Current State & Setup
[dependencies]
askama = "0.16"
# For web frameworks, ADD askama_web separately (see §3):
askama_web = { version = "0.16", features = ["axum-0.8"] }
- Do not depend on
askama_axum,askama_actix,askama_warp, oraskama_rocket(removed when 0.13 unified them), noraskama_gotham/askama_tide(abandoned since 2023 on askama ^0.12). There is noaskama_actix_webcrate. rinjaandrinja_axumare deprecated (2024 fork, re-unified asaskamain early 2025): migrate toaskama/askama_web.- MSRV: 1.81 through 0.13.x, 1.83 in 0.14, 1.88 since 0.15.
Features
Default: config (reads askama.toml), derive, std, urlencode. Opt-in: serde_json (the json filter), code-in-doc (in_doc); full = default + both. A gated filter does not resolve until its feature is on:
# WRONG when a template uses {{ data | json }}
askama = "0.16"
# RIGHT
askama = { version = "0.16", features = ["serde_json"] }
- Spell it
serde_json(underscore, since 0.13);serde-jsonno longer exists. - Removed in 0.13: features
humansize,markdown,serde-yaml. The size filter isfilesizeformat, always available; there is nohumansizefilter. Usecomrak/yaml-rust2directly. #![no_std]: without thestdfeaturewrite_into()is gone, withoutallocalsorender()and many filters. Render withrender_intointo acore::fmt::Writesink, never anio::Writecursor.
Minimal Example
// fragment
use askama::Template;
#[derive(Template)]
#[template(path = "hello.html")] // templates/hello.html holds: Hello, {{ name }}!
struct HelloTemplate<'a> { name: &'a str }
HelloTemplate { name: "world" }.render()? // -> Result<String, askama::Error>
- Templates live in
templates/at the crate root (next toCargo.toml) by default. Override viaaskama.toml(see §11). - Name each struct field exactly as the template names the variable:
{{ name }}reads fieldname. pathis relative to the template directory, never to the crate root.sourcealways needsext: with no file there is no extension to pick the escaper from.
// fragment
#[template(path = "templates/hello.html")] // WRONG: looks for templates/templates/hello.html
#[template(path = "hello.html")] // RIGHT
#[template(source = "Hello {{ name }}")] // WRONG: no `ext`, does not compile
#[template(source = "Hello {{ name }}", ext = "txt")] // RIGHT
2. Rendering API: Use the Right Method
| Method | Output | When to use |
|---|---|---|
tmpl.render() | Result<String, askama::Error> | Default. Allocates a new String. |
tmpl.render_into(&mut writer) | writes into impl fmt::Write | Reusing a buffer, nested rendering. |
tmpl.write_into(&mut writer) | writes into impl io::Write | Writing directly to a socket / file. |
- Never render with
.to_string()orformat!("{}", tmpl): they route through a vtable at runtime and run 100-200% slower. - A custom type printed in a hot template: implement
askama::FastWritable(fn write_into(&self, dest: &mut dyn fmt::Write, _: &dyn askama::Values) -> askama::Result<()>) besideDisplay; askama prefers it.Display::fmtdelegates:askama::FastWritable::write_into(self, f, askama::NO_VALUES)?; Ok(()). There is noValues::new(). - Trait objects: use
&dyn askama::DynTemplateand itsdyn_render()/dyn_render_into().Templateis not dyn-compatible, soBox<dyn Template>does not compile. - There is no
size_hintattribute:#[template(size_hint = ...)]is a compile error (unsupported template attribute). The derive computesSIZE_HINTfrom the template's static text forrender()to preallocate; override it only by hand-implementingTemplate. - Removed in 0.13+: the
Template::EXTENSIONandTemplate::MIME_TYPEassociated fields no longer exist. - Runtime values that aren't on the struct:
tmpl.render_with_values(&values)with aHashMap<&str, Box<dyn Any>>or one(&str, &dyn Any)tuple; plainrender()passes none. The template pins the type and handles theResult(wrong type or unset key is anErr):
{% if let Ok(name) = "name"|value::<&str> %}name is {{ name }}{% endif %}
{% if let Ok(age) = askama::get_value::<u32>("age") %}age is {{ age }}{% endif %}
3. Web Framework Integration
Two paths. Pick one.
Path A: Manual (Simplest, No Extra Crate)
Call .render(), wrap the string in the framework's HTML response type, and propagate the askama::Error.
// fragment
use axum::response::{Html, IntoResponse};
async fn index() -> Result<impl IntoResponse, AppError> {
Ok(Html(IndexTemplate { title: "Home" }.render()?))
}
// WRONG: `-> Result<String, AppError>` with `Ok(tmpl.render()?)` sends no HTML content type.
AppError: IntoResponseandAppError::from(askama::Error)must exist, e.g. athiserrorvariantRender(#[from] askama::Error). Never.map_err(|e| e.into_box())on every render call.
Path B: askama_web with WebTemplate
One derive implements the response trait for whichever feature flag you turned on. Never hand-write IntoResponse / Responder / Reply per template struct.
// fragment
#[derive(askama::Template, askama_web::WebTemplate)]
#[template(path = "hello.html")]
struct HelloTemplate { name: String }
async fn hello() -> HelloTemplate { HelloTemplate { name: "world".into() } }
Returns 200 OK, Content-Type: text/html; charset=utf-8. Render errors become 500 with no stylized error page; use Path A when the error page must be styled.
Per-target feature flags for askama_web: axum-0.8 / axum-0.7 / axum-core-0.5 / axum-core-0.4, actix-web-4, rocket-0.5, warp-0.4 / warp-0.3, poem-3, trillium-0.2, cot-0.3 / cot-0.4 / cot-0.5 / cot-0.6 / cot_core-0.6. Also derive (WebTemplate derive, on by default), eprintln, and the logging-backend flags log-0.4 / tracing-0.1 (one of each, shared across all integrations).
4. #[template(...)] Attribute Options
| Key | Example | Purpose |
|---|---|---|
path | path = "hello.html" | File in templates dir. Extension drives escaping. |
source | source = "Hi {{ name }}" | Inline template; requires ext. |
ext | ext = "html" | Extension used to pick the escaper (§12). |
escape | escape = "none" or "html" | Override auto-escape. |
whitespace | whitespace = "suppress" | Per-template WS mode ("preserve" / "suppress" / "minimize"); overrides askama.toml. |
syntax | syntax = "foo" | Use a custom syntax defined in askama.toml. |
config | config = "config.toml" | Override config path (default askama.toml). |
print | print = "code" / "ast" / "all" / "none" | Compile-time debug: prints the parsed AST and/or generated code to stderr. |
block | block = "hello" | Render just one block of the file; no second template needed. Fields outside that block aren't required. Good for HTMX fragments. |
blocks | blocks = ["title", "content"] | Generates one as_<block>() method per block, each returning impl Template + '_: page.as_title().render(). |
in_doc | in_doc = true | Source is in the item's doc comment (inside an ```askama fenced block). Requires ext and the code-in-doc feature. |
askama | askama = $crate::__askama | Override the askama crate path. Needed when re-exporting from a macro-defining crate. |
- Cannot combine
pathandsource. pathandsourcemust be string literals known at compile time, the same constraint{% include %}paths have (§10): no template chosen at runtime from a variable.#[derive(Template)]works on an enum: each variant may carry its own#[template(...)]. A variant without one needs an enum-level#[template(...)]as its default.
5. Expressions
Literals and Types
{{ expr }}prints only types that implementDisplay. Tuple(1, 2), array[1, 2, 3]and array-repeat[0; 4](0.15) literals are values forletand call arguments;foriterates the array forms, never a tuple.{{ (1, 2) }}does not compile.- Struct construction:
{{ MyStruct { field1: 1, field2: "x" }.to_string() }}. Struct expressions are values, not just via.to_string()(0.15):{{ Point { x: 1, y: 2 } }}. Struct-update syntax works:{{ Point { x: 1, ..Default::default() } }}.
Variable Access
{{ name }}: field on template struct;{{ user.name }}: dotted path (fields or methods);{{ crate::MAX_USERS }}: constants from your crate.- Reading follows Rust borrow rules. Methods can be called; beware self-recursion:
{{ self }}or a method returningselfoverflows the stack throughDisplay. {% if x is defined %}/is not definedtests plain variables only.{% if x.y is defined %}does not compile.- There is no
lengthfilter: call{{ items.len() }}.
Operators (Mostly like Rust)
- Bitwise are RENAMED (since 0.13, to avoid filter-pipe conflict):
|->bitor,&->bitand,^->xor. Precedence unchanged.
{% if my_bitset & 1 != 0 %}set!{% endif %} {# WRONG #}
{% if my_bitset bitand 1 != 0 %}set!{% endif %} {# RIGHT #}
- Prefix
&and*reference and dereference as in Rust:{% let x = &"bla" %}{% if *x == "bla" %}yes{% endif %}. Thebitandrename covers binary&only. - Concat
~:{{ a ~ b ~ c }}is shorthand for{{ a }}{{ b }}{{ c }}. Must have spaces around it to disambiguate from whitespace control;{{ a~b }}breaks. ascast:{{ x as i64 }}. Only primitive types. Automatically derefs&&&booletc.?works onResultonly, never onOption:
{{ some_result? }}
{{ some_option? }} {# WRONG: does not compile #}
{% if let Some(value) = some_option %}{{ value }}{% endif %} {# RIGHT #}
Function and Method Calls
{{ method() }}->self.method()(method on the template struct). A bare name is always taken as a method.{{ self::function() }}-> free function in the current module{{ super::b::f() }},{{ crate::utils::f() }}-> function in another module{{ (closure)(12) }}-> calling a closure stored in a field; parens required{{ some_macro!(field) }}-> Rust macro. Askama won't infer field references inside macro args. Bind the field first:{% let field = field %}.
{{ foo(123) }} {# WRONG for a free function: compiled as self.foo(123) #}
{{ self::foo(123) }} {# RIGHT #}
6. Control Flow
if / else if / else
{% if a %}…{% else if b %}…{% else %}…{% endif %}. {% elif b %} is the same as {% else if b %}.
for
{% for user in users %}<li>{{ user.name }}</li>{% endfor %}
- Filter clause:
{% for user in users if user.active %} - Else clause (runs if iter was empty or all filtered out); use it instead of an
{% if %}guard around the loop:{% for u in users %}...{% else %}No one here.{% endfor %} {% break %}and{% continue %}work inside a loop.- Loop variables (the complete list; Askama exposes fewer of them than Jinja does):
loop.index(1-based),loop.index0(0-based),loop.first,loop.last. Use them instead of a hand-rolledlet mutcounter. loop.cycle(seq)(method call):{{ loop.cycle(["a", "b"]) }}cycles per iteration.seqmay be a variable holding an array or slice; an empty array literal is a compile error.- No
loop.length,loop.revindex,loop.changed,loop.previtem,loop.nextitem. If you need these, compute in Rust or use modulo onloop.index.
match / when (for Enums, Options, Results)
A {% match %} must be exhaustive and non-empty: cover every case or end with {% else %} (sugar for {% when _ %}).
{% match result %}{% when Ok(val) %}Good: {{ val }}.{% endmatch %} {# WRONG: no arm for Err #}
{% match result %}{% when Ok(val) %}Good: {{ val }}.{% else %}Bad.{% endmatch %} {# RIGHT #}
withis optional:{% when Some with (val) %}and{% when Some(val) %}are both valid; do not rewrite one into the other.- Variant patterns: literal
{% when Some with ("foo") %}, tuple{% when Variant with (a, b) %}, struct{% when Variant { field } %}or{% when Variant { field: val } %}to rename, enum path{% when Self::Circle { radius } %}. - Other patterns: slice with rest
{% when [first, ..] %}, literal{% when 3 %}, alternatives{% when 1 | 4 | 86 %}, wildcard{% when _ %}or{% else %}. - Text inside a
{% match %}belongs to an arm: between{% match %}and the first{% when %}, and between an{% endwhen %}and the next tag, only whitespace and{# comments #}may appear; anything else does not compile.{% endwhen %}(closing an arm, for djLint) is optional.
Assignments and Variable Declarations
{% let name = user.name %} {# immutable binding #}
{% let mut it = xs.iter() %} {# mutable binding #}
{% set x = 4 %} {# alias for let (Jinja compat) #}
{% let n: u32 = 12 %} {# type annotation, as in Rust #}
{% decl val %} {# declare WITHOUT value; let/set can't since 0.16 #}
{% if cond %}{% let val = "a" %}{% else %}{% let val = "b" %}{% endif %}
{{ val }}
decl(aliasdeclare) is the only valueless declaration since 0.16. Bare{% let x %}/{% set x %}with no=now starts a let/set block instead.- let/set blocks (0.16) capture a rendered block into a
Stringvariable, instead of building it withformat!in Rust:{% let heading %}{{ title }} on {{ site }}{% endlet %}, then{{ heading }}. - Compound assignment uses the
{% mut %}tag (0.16), not barelet:{% mut counter += i %}. Every Rust compound operator (+=,-=,*=, …) works; the target must be amutbinding.
{% let counter = 0 %}{% mut counter += 1 %} {# WRONG: counter is not mut #}
{% let mut counter = 0 %}{% mut counter += 1 %} {# RIGHT #}
- Shadowing is allowed, same as Rust: a second
{% let x = .. %}/{% set x = .. %}makes a new binding, it does not mutate the old one. {% let x = obj.field %}holds a reference; a plain variable, a filtered value, an expression ending in?(x?) or a multi-part expression is moved or copied (since 0.14). Dereference to compare:{% if x | deref == String::from("b") %}.- Do not prefix variables with
__askama, name onecaller(reserved since 0.15), or use Rust keywords.
Filter Blocks
Apply one or more filters to a whole block instead of repeating the chain on every expression: {% filter lower | capitalize %}{{ t }} / HELLO / {{ u }}{% endfilter %}
Raw Blocks
{% raw %}{{ shown as-is }}{% endraw %} prints its content verbatim, without templating.
7. Whitespace Control: Three Operators, Not One
| Operator | Name | Effect |
|---|---|---|
- | suppress | Remove all whitespace on that side |
~ | minimize | Collapse to a single space/newline |
+ | preserve | Keep whitespace as-is (overrides config) |
Usage: put right after {%/{{ or right before %}/}}, inside the delimiter: {%- if x %} strips before the tag, {% for x in xs ~%} minimizes after it. {~% if x %} is literal text.
- Nothing is trimmed by default (no Jinja
trim_blocks):preserverenders every newline and indent around a tag; only one trailing newline of the template is dropped. Add-where output must be tight; use~where one newline or space must survive. - Precedence: inline operator >
#[template(whitespace = ...)]>askama.toml. - When two inline controls point at the same span, Suppress always wins; between Minimize and Preserve, whichever operator sits on the tag AFTER the gap wins (positional; the book's flat
Suppress > Minimize > Preservetable is wrong there). - Whitespace control on
{% extends %}is an accepted no-op, not a compile error (the book's "rejected" is stale).
8. Comments
Nested block comments are supported: {# outer {# nested #} still in outer #}
9. Inheritance (extends / block / super)
base.html:
<title>{% block title %}{{ title }} · Site{% endblock %}</title>
<main>{% block content %}<p>default</p>{% endblock %}</main>
page.html:
{% extends "base.html" %}
{% block title %}Index{% endblock %}
{% block content %}
{{ super() }} {# inject the parent block's contents #}
<h1>Hello!</h1>
{% endblock %}
A child template puts all of its markup inside {% block %} overrides. The extending template's top-level content outside blocks is ignored, with no compile error:
{% extends "base.html" %}
<h1>Index</h1> {# WRONG: never rendered #}
{% block content %}<h1>Index</h1>{% endblock %} {# RIGHT #}
{% extends %}must be the first tag of the template.- An overriding block replaces the parent block; call
{{ super() }}inside it to keep the parent's contents. - Multi-layer inheritance is supported. A base template must define at least one block for inheritance to work.
- Askama looks for the extended template relative to the extending one first, then relative to the config'd template dirs.
- Put
{% block %}at the top level or inside another block. The book forbids blocks insideif/else/for; 0.16 compiles them and inheritance overrides correctly, but top-level or block-nested stays the safe form. - Duplicate
{% block %}names in the same template are a hard compile error since 0.16, previously only a warning.
10. Includes, Macros, and Composition
{% include %}
{% for item in items %}{% include "item.html" %}{% endfor %}
- Path must be a string literal (known at compile time). Lookup: relative to including template first, then template dirs.
- The included template has full access to the caller's scope, including loop locals.
Macros
Define with {% macro heading(arg) %}<h1>{{ arg }}</h1>{% endmacro %} (optional named endmacro: {% endmacro heading %}), call with {{ heading("Title") }}.
- Expression-call syntax (0.15) is the call form for a macro without a
callerbody (named args allowed too).{% call heading("Title") %}with no body and no{% endcall %}does not parse. - Macro args can carry default values and type annotations (0.15/0.16):
{% macro test(value: Option<u32>, extra: Option<u32> = None) %}. - Named arguments (must come AFTER positional):
{{ h(bold="x", arg="y") }} - Import macros from another file:
{%- import "macros.html" as m -%}, then{{ m::heading("hi") }}. - Put
{% macro %}and{% import %}at the template's top level: below it (e.g. inside a{% block %}) they are a compile error.
Call-Block Syntax (Macros with Inner Content)
{% macro card() %}<div class="card">{{ caller() }}</div>{% endmacro %}
{% call card() %}
<p>Body passed into the macro.</p>
{% endcall %}
caller() inside the macro renders the block passed to {% call %}...{% endcall %}. With arguments: {% call(user) dump_users(list) %}...{% endcall %} makes the macro's caller(user) render the body once per invocation. Guard an optional body with {% if caller is defined %}.
Nested and Recursive Templates
- Render-in-place: embed a Template-derived type as a field (
struct Outer { s1: Inner });{{ s1 }}auto-renders via itsDisplayimpl. In an HTML outer template write{{ s1 | safe }}, or the inner markup is escaped (<div>). - Self-include does NOT work. Recurse with an explicit
.render()call on a field of the template's own type (children: &'a [Item<'a>]):{% for child in children %}{{ child.render()? | safe }}{% endfor %}. An HTML template escapes the child's markup without| safe;escape = "none"needs none. Prefer a custom iterator + plain loop when possible.
11. Configuration: askama.toml
Place at crate root (next to Cargo.toml). All sections are optional.
[general]
dirs = ["templates"] # default; globs OK (0.16): ["templates/*"], ["templates/**"]
whitespace = "preserve" # or "suppress" | "minimize"
[[syntax]] # custom delimiters (e.g. to avoid collisions with LaTeX or Vue)
name = "vue"
block_start = "[%"
block_end = "%]"
expr_start = "[["
expr_end = "]]"
comment_start = "[#"
comment_end = "#]"
[[escaper]] # apply askama::filters::Text (no escaping) to .js files
path = "askama::filters::Text"
extensions = ["js"]
- Use a custom syntax per-template with
#[template(path = "...", syntax = "vue")], or for every template withdefault_syntax = "vue"under[general]. - Each delimiter value is at least two characters; an omitted key keeps the default delimiter.
- An
[[escaper]]pathmust name a type in scope of the template that implementsaskama::filters::Escaper. An extension that no[[escaper]]block and no default covers (.js,.kml) is a compile error, never a silent HTML fallback.
12. Auto-Escaping
The file extension (or ext) picks the escaper:
- HTML escaper:
askama,html,htm,j2,jinja,jinja2,rinja,svg,xml - Text (no escape):
md,yml,none,txt(and the empty extension)
Askama escapes <, >, &, ", ' per OWASP recommendations when the extension implies HTML. Never pre-escape a value in Rust (it renders as &lt;) and never switch escaping off to let one value through:
{{ user_bio }} {# RIGHT: escaped automatically #}
{{ trusted_html | safe }} {# RIGHT: one trusted expression #}
{{ user_bio | safe }} {# WRONG: untrusted input, XSS #}
json output goes bare into a double-quoted attribute; with | safe it goes bare into <script>, a single-quoted attribute or HTML text (<pre>):
<li data-extra="{{ data | json }}"> {# RIGHT #}
<script>var data = {{ data | json | safe }};</script> {# RIGHT #}
<script>var data = "{{ data | json | safe }}";</script> {# WRONG: quoted inside <script> #}
<li data-extra="{{ data | json | safe }}"> {# WRONG: `safe` inside a double-quoted attribute #}
- Per-template override:
#[template(escape = "html")]orescape = "none", instead of renaming the file. impl askama::filters::HtmlSafe for MyType {}only on a type whoseDisplaynever emits<,>,&,",': it skips escaping as a speed-up, never a guarantee. Where output must stay unescaped, write| safe.{{ value | escape }}or{{ value | e }}applies the template's own escaper. In anescape = "none"template a bare| eescapes nothing: write| e("html").
13. Built-in Filters
All filters use value | filter_name(args). Named arguments are supported and must come after positional ones: {{ count | pluralize(plural = "gies") }}.
Plain filters: center (in a field of given width), lower / lowercase, upper / uppercase, title / titlecase, trim, wordcount, safe, unique (requires std), ref / deref.
| Filter | Behavior |
|---|---|
capitalize | First char upper, all others lowercased: hElLO -> Hello |
escape / e | Escape with the template's escaper, or a named one: e("html") |
filesizeformat | Bytes -> SI decimal units: 1024 -> 1.02 kB; filesizeformat(precision = 3) |
fmt(fmtstr) | Apply Rust format string to the piped value |
format(args...) | Like format!(); the piped value is the format string |
indent(n) / indent(prefix) | Indent every line but the first; blank lines stay bare. indent(4, true, true) indents those too |
join(sep) | Join iterable into string. Prints once; a second print of the same value is empty |
linebreaks | \n -> <br/>, \n\n -> <p> |
linebreaksbr | Every \n -> <br/> |
paragraphbreaks | Only \n\n -> <p>. These three escape their input (since 0.13): never pipe through escape first |
pluralize(singular = "", plural = "s") | Suffix based on ±1 of the piped count |
reject(value) / reject(callback) | Filter iterator: reject(crate::is_odd). There is no reject_with filter |
truncate(n) | Limit length, appends ... if truncated |
assigned_or(fallback) | Fallback if the value is in its default state: None, Err, but also "", 0, false. Never where 0 / "" is a valid value (0.15) |
defined_or(fallback) | Fallback if the identifier is undefined; LHS must be an identifier (0.15) |
default(val[, bool]) | Jinja-compat: acts as defined_or, or as assigned_or when 2nd arg is true. Prefer the two above (0.15) |
json / tojson | Compact JSON; json(2) pretty-prints. Feature serde_json (opt-in) |
urlencode | Does NOT encode /: for path segments and query parts. Feature urlencode (default) |
urlencode_strict | Encodes / too: only when the server cannot take / in a query string. Same feature |
fmttakes the literal second,formatfirst:{{ value | fmt("{:?}") }}or{{ "{:?}" | format(value) }}, never{{ value | format("{:?}") }}.{{ count }} item{{ count | pluralize }}: pipe the count itself.
14. Custom Filters
Since 0.15 a custom filter is a plain fn annotated with #[askama::filter_fn]; a bare fn in mod filters no longer compiles. Put it in a module named filters in scope of the #[derive(Template)] struct, or call it via an explicit path ({{ x | mymod::myfilter }}).
Mandatory signature: first arg is the piped-in value (any type; impl Display or a generic bound is typical, accepting owned and borrowed), second is &dyn askama::Values (the runtime-values env, since 0.14). Returns askama::Result<T>. In a chain only the last filter's T must be Display.
use askama::Template;
#[derive(Template)]
#[template(source = "{{ s | shout }}", ext = "txt")]
struct Msg<'a> { s: &'a str }
mod filters {
#[askama::filter_fn]
pub fn shout<T: std::fmt::Display>(s: T, _env: &dyn askama::Values) -> askama::Result<String> {
Ok(s.to_string().to_uppercase() + "!")
}
}
- Required extra args are more params after the two mandatory ones:
fn repeat(s: impl Display, _: &dyn Values, n: usize)invoked as{{ s | repeat(4) }}. - Optional args (must follow every required one) declare their default with
#[optional(...)]:#[optional(None)] a: Option<&str>,#[optional("hi")] b: &str. - Named-argument invocation works (named must follow positional):
{{ x | f(b = "yo") }}. Lifetimes (0.15.1) andwherebounds (0.15.2) on the fn are allowed. - Built-in filter names take precedence over custom ones; be explicit with
{{ x | filters::myfilter }}if you shadow one. - A filter that produces HTML returns
askama::Result<askama::filters::Safe<String>>, endingOk(askama::filters::Safe(html)), or its output is escaped. The mark holds only for the last filter of a chain; a later filter voids it. - Filter fns and
render()/render_into()are synchronous only. No async support; anasync fndoesn't satisfy the#[askama::filter_fn]signature.
15. Debugging Tips
- Playground: https://play.askama.rs shows the generated code for a template.
- Compile errors: Askama's own errors carry the template's
file:line:column; type errors in generated code point at#[derive(Template)]unless the nightly-onlynightly-spansfeature is on. Lifetime / ownership errors in generated code usually mean a field got moved. Take a reference, or use&in the template. - Docs: https://askama.rs (book, canonical syntax reference), https://docs.rs/askama (API, full filter list).
16. Checklist
Run over your own diff:
-
Cargo.toml: noaskama_axum/rinja*; every gated filter has its feature (serde_jsonforjson). -
pathhas notemplates/prefix; everysourcehas anext. - Handlers return an HTML response type and propagate
askama::Error; nothing renders through.to_string(). - No
&,|,^as bitwise operators; free functions are called by path (self::f());?only onResult. - Every
{% match %}is exhaustive or ends with{% else %}. - A mutated variable is
let mutand changed with{% mut %}. - A child template keeps all markup inside blocks and repeats no block name.
- No hand pre-escaping; every
| safemarks trusted markup;jsonplacement follows §12. - Custom filters have
#[askama::filter_fn],&dyn askama::Valuessecond, anaskama::Resultreturn.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |