### Capitalize Filter Example

Source: https://askama.rs/en/stable/filters.html

Provides a concrete example of the 'capitalize' filter's output.

```Askama
{{ "hello" | capitalize }}
```

--------------------------------

### Check Block Start Syntax

Source: https://askama.rs/en/stable/doc/src/askama_parser/node.rs.html

Ensures that a block node starts correctly and handles cases where the block is unexpectedly empty.

```rust
fn check_block_start<'a: 'l, 'l>(
    i: &mut InputStream<'a, 'l>,
    start: Span,
    node: &str,
    expected: &str,
) -> ParseResult<'a, ()> {
    if i.is_empty() {
        return cut_error!(
            format!("expected `{expected}` to terminate `{node}` node, found nothing"),
            start,
        );
    }
    i.state.syntax.block_start.void().parse_next(i)
}
```

--------------------------------

### Span::start() - Get an empty Span at the start

Source: https://askama.rs/en/stable/doc/askama_parser/struct.Span.html

Returns an empty Span that points to the start of the current Span.

```rust
pub fn start(self) -> Self
```

--------------------------------

### Center Filter Example

Source: https://askama.rs/en/stable/filters.html

Demonstrates the 'center' filter with a specific width, showing the resulting padding.

```Askama
-{{ "a" | center(5) }}-
```

--------------------------------

### Askama Template Parse Tree Example

Source: https://askama.rs/en/stable/print.html

This is an example of the parse tree output for a simple Askama template, showing literal strings and expressions.

```text
[Lit("", "Hello,", " "), Expr(WS(false, false), Var("name")), Lit("", "!", "\n")]
```

--------------------------------

### Askama Generated Rust Code Example

Source: https://askama.rs/en/stable/debugging.html

This is an example of the Rust code generated by Askama for a template. It shows the `render_into` implementation that writes the template content to a writer.

```rust
impl<'a> askama::Template for HelloWorld<'a> {
    fn render_into<AskamaW>(&self, __askama_writer: &mut AskamaW) -> askama::Result<()> 
    where
        AskamaW: core::fmt::Write + ?Sized,
    {
        __askama_writer.write_str("Hello, ")?;
        match (
            &((&&askama::filters::AutoEscaper::new(
                &(self.name),
                askama::filters::Html,
            ))
                .askama_auto_escape()?),
        ) {
            (expr2,) => {
                (&&askama::filters::Writable(expr2)).askama_write(__askama_writer)?;
            }
        }
        __askama_writer.write_str("!")?;
        Ok(())
    }
    const SIZE_HINT: usize = 11usize;
}
```

--------------------------------

### Basic HTML Template Example

Source: https://askama.rs/en/stable/introduction.html

Create a simple HTML template file named 'hello.html' in the 'templates' directory.

```html
Hello, {{ name }}!
```

--------------------------------

### Askama `upper` Filter Example Implementation

Source: https://askama.rs/en/stable/doc/askama/filters/fn.upper.html

Provides a Rust example showing the `upper` filter in action. It defines a template struct and asserts that the output is correctly uppercased for different input strings.

```rust
/// ```jinja
/// <div>{{ word|upper }}</div>
/// ```
#[derive(Template)]
#[template(ext = "html", in_doc = true)]
struct Example<'a> {
    word: &'a str,
}

assert_eq!(
    Example { word: "foo" }.to_string(),
    "<div>FOO</div>"
);

assert_eq!(
    Example { word: "FooBar" }.to_string(),
    "<div>FOOBAR</div>"
);
```

--------------------------------

### Example Usage and Assertion for wordcount Filter

Source: https://askama.rs/en/stable/doc/askama/filters/fn.wordcount.html

This Rust code provides a complete example of using the 'wordcount' filter. It defines a template struct 'Example', instantiates it with a sample string, renders the template, and asserts that the output matches the expected word count.

```rust
/// ```jinja
/// <div>{{ example|wordcount }}</div>
/// ```
#[derive(Template)]
#[template(ext = "html", in_doc = true)]
struct Example<'a> {
    example: &'a str,
}

assert_eq!(
    Example { example: "askama is sort of cool" }.to_string(),
    "<div>5</div>"
);
```

--------------------------------

### Example: Serializing a Vec<&str> to JSON

Source: https://askama.rs/en/stable/doc/src/askama/filters/json.rs.html

A complete Askama template example demonstrating the `json` filter's usage with a `Vec<&str>`. The output is embedded within an HTML structure.

```rust
# #[cfg(feature = "code-in-doc")] {
# use askama::Template;
/// ```jinja
/// <div><li data-extra='{{data|json|safe}}'>Example</li></div>
/// ```

#[derive(Template)]
#[template(ext = "html", in_doc = true)]
struct Example<'a> {
    data: Vec<&'a str>,
}

assert_eq!(
    Example { data: vec!["foo", "bar"] }.to_string(),
    "<div><li data-extra='[\"foo\",\"bar\"]'>Example</li></div>"
);
# }

```

--------------------------------

### Askama Template Parse Tree Example

Source: https://askama.rs/en/stable/debugging.html

This is an example of the parse tree output for a simple Askama template. It represents the structure of the template before code generation.

```text
[Lit("", "Hello, ", " "), Expr(WS(false, false), Var("name")), Lit("", "!", "\n")]
```

--------------------------------

### Deref Filter Example with Ref

Source: https://askama.rs/en/stable/filters.html

Demonstrates the 'deref' filter in a context where a reference is created using 'ref'.

```Askama
{% let s = String::from("a") | ref %}
{% if s | deref == String::from("b") %}
{% endif %}
```

--------------------------------

### Askama Template Example: urlencode

Source: https://askama.rs/en/stable/doc/src/askama/filters/urlencode.rs.html

A Rust code example showing how to use the `urlencode` filter within an Askama template. It asserts the expected output for a string containing a question mark.

```rust
# #[cfg(feature = "code-in-doc")] {
# use askama::Template;
/// ```jinja
/// <div>{{ example|urlencode }}</div>
/// ```
#[derive(Template)]
#[template(ext = "html", in_doc = true)]
struct Example<'a> {
    example: &'a str,
}

assert_eq!(
    Example { example: "hello?world" }.to_string(),
    "<div>hello%3Fworld</div>"
);
# }

```

--------------------------------

### Example: Pretty-Printing Vec<&str> to JSON

Source: https://askama.rs/en/stable/doc/src/askama/filters/json.rs.html

An Askama template example showcasing the `json` filter with an indentation argument. It serializes a `Vec<&str>` into a nicely formatted JSON string within an HTML `<div>`.

```rust
# #[cfg(feature = "code-in-doc")] {
# use askama::Template;
/// ```jinja
/// <div>{{data|json(4)|safe}}</div>
/// ```

#[derive(Template)]
#[template(ext = "html", in_doc = true)]
struct Example<'a> {
    data: Vec<&'a str>,
}

assert_eq!(
    Example { data: vec!["foo", "bar"] }.to_string(),
    "<div>[\n    \"foo\",\n    \"bar\"\n]</div>"
);
# }

```

--------------------------------

### Rust Example of `center` filter usage

Source: https://askama.rs/en/stable/doc/askama/filters/fn.center.html

An example showing the `center` filter's output in a Rust Askama template. It asserts that a string 'a' centered to a width of 5 results in '  a  ' when enclosed by hyphens.

```rust
/// ```jinja
/// <div>-{{ example|center(5) }}-</div>
/// ```
#[derive(Template)]
#[template(ext = "html", in_doc = true)]
struct Example<'a> {
    example: &'a str,
}

assert_eq!(
    Example { example: "a" }.to_string(),
    "<div>-  a  -</div>"
);
```

--------------------------------

### Result::or Example

Source: https://askama.rs/en/stable/doc/askama/type.Result.html

Demonstrates the behavior of the `or` method, which returns the first `Ok` value encountered or the last `Err` if all are `Err`.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("early error");
let y: Result<u32, &str> = Ok(2);
assert_eq!(x.or(y), Ok(2));

let x: Result<u32, &str> = Err("not a 2");
let y: Result<u32, &str> = Err("late error");
assert_eq!(x.or(y), Err("late error"));

let x: Result<u32, &str> = Ok(2);
let y: Result<u32, &str> = Ok(100);
assert_eq!(x.or(y), Ok(2));
```

--------------------------------

### Assigned Or Filter Example with Option

Source: https://askama.rs/en/stable/filters.html

Illustrates the 'assigned_or' filter with an Option type, providing a fallback when the Option is None.

```Askama
{% let greeting = Some("Hello") %}
{{ greeting.as_ref() | assigned_or("Hi") }}
```

--------------------------------

### Configuring Template Directories with Glob Syntax

Source: https://askama.rs/en/stable/configuration.html

Demonstrates using glob syntax in the `dirs` configuration to include templates from subdirectories.

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

```

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

```

--------------------------------

### Span::as_suffix_of() - Get substring as suffix

Source: https://askama.rs/en/stable/doc/askama_parser/struct.Span.html

Retrieves the substring from the source string starting from the Span's start position.

```rust
pub fn as_suffix_of<'a>(&self, source: &'a str) -> Option<&'a str>
```

--------------------------------

### Actix-web HTML Response

Source: https://askama.rs/en/stable/frameworks.html

Example of returning an HTML response from an Actix-web handler using Askama's render output.

```rust
use actix_web::web::Html;
use actix_web::{Responder, handler};

#[handler]
fn handler() -> Result<impl Responder, AppError> {
    …
    Ok(Html::new(template.render()?))
}
```

--------------------------------

### Parse Expression Start

Source: https://askama.rs/en/stable/doc/src/askama_parser/lib.rs.html

Parses the start delimiter for an expression.

```rust
fn expr_start<'a: 'l, 'l>(i: &mut InputStream<'a, 'l>) -> ParseResult<'a, ()> {
    i.state.syntax.expr_start.void().parse_next(i)
}

```

--------------------------------

### Parse Block Start

Source: https://askama.rs/en/stable/doc/src/askama_parser/lib.rs.html

Parses the start of a block construct within the input stream.

```rust
fn block_start<'a: 'l, 'l>(i: &mut InputStream<'a, 'l>) -> ParseResult<'a, ()> {
    i.state.syntax.block_start.void().parse_next(i)
}

```

--------------------------------

### Configure Custom Syntax Definitions

Source: https://askama.rs/en/stable/doc/src/askama_derive/config.rs.html

Demonstrates how to define custom syntax configurations, including default syntax and specific delimiters for different syntaxes.

```rust
#[cfg(feature = "config")]
#[test]
fn add_syntax() {
    let raw_config = r#"
        [general]
        default_syntax = "foo"

        [[syntax]]
        name = "foo"
        block_start = "{<"

        [[syntax]]
        name = "bar"
        expr_start = "{!"
        "#;

        let default_syntax = Syntax::default();
        let config = Config::new(raw_config, None, None, None, None).unwrap();
        assert_eq!(config.default_syntax, "foo");

        let foo = config.syntaxes.get("foo").unwrap();
        assert_eq!(foo.block_start, "{<");
        assert_eq!(foo.block_end, default_syntax.block_end);
        assert_eq!(foo.expr_start, default_syntax.expr_start);
        assert_eq!(foo.expr_end, default_syntax.expr_end);
        assert_eq!(foo.comment_start, default_syntax.comment_start);
        assert_eq!(foo.comment_end, default_syntax.comment_end);

        let bar = config.syntaxes.get("bar").unwrap();
        assert_eq!(bar.block_start, default_syntax.block_start);
        assert_eq!(bar.block_end, default_syntax.block_end);
        assert_eq!(bar.expr_start, "{!);
        assert_eq!(bar.expr_end, default_syntax.expr_end);
        assert_eq!(bar.comment_start, default_syntax.comment_start);
        assert_eq!(bar.comment_end, default_syntax.comment_end);
    }

```

--------------------------------

### Rust Template Rendering Example

Source: https://askama.rs/en/stable/template_syntax.html

Demonstrates rendering a template that includes another template using Rust structs and Askama's Template derive macro. Shows how to pass data between templates.

```rust
use askama::Template;
#[derive(Template)]
#[template(source = "Section 1: {{ s1 }}", ext = "txt")]
struct RenderInPlace<'a> {
   s1: SectionOne<'a>
}

#[derive(Template)]
#[template(source = "A={{ a }}\nB={{ b }}", ext = "txt")]
struct SectionOne<'a> {
   a: &'a str,
   b: &'a str,
}

let t = RenderInPlace { s1: SectionOne { a: "a", b: "b" } };
assert_eq!(t.render().unwrap(), "Section 1: A=a\nB=b")
```

--------------------------------

### Configure Template Directories with Glob Patterns

Source: https://askama.rs/en/stable/doc/src/askama_derive/config.rs.html

Demonstrates how to configure template directories using glob patterns. The first example shows top-level directory inclusion, while the second includes nested subdirectories.

```rust
fn test_config_dirs_glob() {
    let root = manifest_root();
    let config = Config::new(
        "[general]\ndirs = [\"templates/*\"]",
        None,
        None,
        None,
        None,
    )
    .unwrap();
    // We ensure that it includes only top level folders.
    assert_eq!(config.dirs, vec![root.join("templates/sub")]);

    let config = Config::new(
        "[general]\ndirs = [\"templates/**\"]",
        None,
        None,
        None,
        None,
    )
    .unwrap();
    // We ensure that it includes top level and sub-folders.
    assert_eq!(
        config.dirs,
        vec![root.join("templates/sub"), root.join("templates/sub/sub1")]
    );
}
```

--------------------------------

### Span::no_span() - Create an empty Span at the start

Source: https://askama.rs/en/stable/doc/askama_parser/struct.Span.html

Creates an empty Span that points to the start of the string. This is a constant function.

```rust
pub const fn no_span() -> Span
```

--------------------------------

### SourceSpan Initialization Methods

Source: https://askama.rs/en/stable/doc/src/askama_derive/spans.rs.html

Provides methods to create SourceSpan instances. `empty()` creates a span at the call site. `from_source()` parses a string literal into a SpannedSource. `from_path()` creates a SpannedPath from a configuration literal.

```rust
pub(crate) fn empty() -> SourceSpan {
    Self::Empty(Span::call_site())
}

pub(crate) fn from_source(source: LitStr) -> Result<(String, Self), CompileError> {
    let (source, span) = SpannedSource::new(source)?;
    Ok((source, Self::Source(span)))
}

#[cfg(feature = "external-sources")]
pub(crate) fn from_path(config: LitStr) -> Result<SourceSpan, CompileError> {
    Ok(Self::Path(SpannedPath::new(config)?))
}
```

--------------------------------

### Get Error Cause (Deprecated)

Source: https://askama.rs/en/stable/doc/askama/enum.Error.html

Deprecated method to get the cause of the error. Use `Error::source` which supports downcasting.

```rust
fn cause(&self) -> Option<&dyn Error>
```

--------------------------------

### Enable All Features with "full"

Source: https://askama.rs/en/stable/features.html

The `"full"` feature flag enables all implemented features, including `default`, `code-in-doc`, and `serde_json`, for a quick start.

```toml
full = ["default", "code-in-doc", "serde_json"]
```

--------------------------------

### Result::unwrap_err_unchecked Example (Ok - Undefined Behavior)

Source: https://askama.rs/en/stable/doc/askama/type.Result.html

Demonstrates the unsafe usage of `unwrap_err_unchecked` on an `Ok` variant, which leads to undefined behavior.

```rust
let x: Result<u32, &str> = Ok(2);
unsafe { x.unwrap_err_unchecked() }; // Undefined behavior!
```

--------------------------------

### Askama Configuration: Glob Syntax for Template Directories

Source: https://askama.rs/en/stable/print.html

Use glob syntax in the `dirs` configuration to specify template locations, including subdirectories.

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

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

--------------------------------

### Get Error Description (Deprecated)

Source: https://askama.rs/en/stable/doc/askama/enum.Error.html

Deprecated method to get a string description of the error. Use the `Display` implementation or `to_string()` instead.

```rust
fn description(&self) -> &str
```

--------------------------------

### Import and Use Macro from External File

Source: https://askama.rs/en/stable/template_syntax.html

Demonstrates importing macros from an external file ('macro.html') using a named scope and then invoking the imported macro.

```askama
{% import "macro.html" as scope %}

{{ scope::heading("test") }}
```

--------------------------------

### Configure Custom Syntax Definitions (Array Format)

Source: https://askama.rs/en/stable/doc/src/askama_derive/config.rs.html

Shows an alternative way to define custom syntax configurations using an array format for the 'syntax' key.

```rust
#[cfg(feature = "config")]
#[test]
fn add_syntax_two() {
    let raw_config = r#"
        syntax = [{ name = "foo", block_start = "{<" },
                  { name = "bar", expr_start = "{!" } ]

        [general]
        default_syntax = "foo"
        "#;

        let default_syntax = Syntax::default();
        let config = Config::new(raw_config, None, None, None, None).unwrap();
        assert_eq!(config.default_syntax, "foo");

        let foo = config.syntaxes.get("foo").unwrap();
        assert_eq!(foo.block_start, "{<");
        assert_eq!(foo.block_end, default_syntax.block_end);
        assert_eq!(foo.expr_start, default_syntax.expr_start);
        assert_eq!(foo.expr_end, default_syntax.expr_end);
    }

```

--------------------------------

### Askama Default Configuration: Template Directories

Source: https://askama.rs/en/stable/print.html

Configure the directories Askama searches for templates using the `dirs` key in `askama.toml`. This example sets the search path to a 'templates' directory.

```toml
[general]
dirs = ["templates"]
# Unless you add a `-` in a block, whitespace characters won't be trimmed.
whitespace = "preserve"
```

--------------------------------

### Getting Mutable References with `as_mut()`

Source: https://askama.rs/en/stable/doc/askama/type.Result.html

Shows how to use `as_mut()` to get mutable references to the contents of a `Result`. This enables in-place modification of the `Ok` or `Err` value.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### Askama Template Example: urlencode_strict

Source: https://askama.rs/en/stable/doc/src/askama/filters/urlencode.rs.html

A Rust code example demonstrating the `urlencode_strict` filter in an Askama template. It asserts the output for a string containing forward slashes, which are encoded by this filter.

```rust
# #[cfg(feature = "code-in-doc")] {
# use askama::Template;
/// ```jinja
/// <a href='{{ example|urlencode_strict }}'>Example</a>
/// ```
#[derive(Template)]
#[template(ext = "html", in_doc = true)]
struct Example<'a> {
    example: &'a str,
}

assert_eq!(
    Example { example: "/hello/world" }.to_string(),
    "<a href='%2Fhello%2Fworld'>Example</a>"
);
# }

```

--------------------------------

### Using filesizeformat Filter

Source: https://askama.rs/en/stable/doc/askama/filters/fn.filesizeformat.html

Demonstrates how to use the `filesizeformat` filter within an Askama template to display a byte size in a human-readable format. The filter takes the byte count and an optional precision argument.

```rust
pub fn filesizeformat(
    bytes: u128,
    precision: u8,
) -> Result<FilesizeFormatFilter, Infallible>

```

```rust
#[derive(Template)]
#[template(
    source = "Filesize: {{ size_in_bytes | filesizeformat }}.",
    ext = "html"
)]
struct Example {
    size_in_bytes: u64,
}

let tmpl = Example { size_in_bytes: 1_234_567 };
assert_eq!(tmpl.to_string(),  "Filesize: 1.23 MB.");

```

--------------------------------

### Specify Configuration File Path

Source: https://askama.rs/en/stable/creating_templates.html

Sets the path to a custom configuration file for Askama, relative to the crate root.

```rust
#[derive(Template)]
#[template(path = "hello.html", config = "config.toml")]
struct HelloTemplate<'a> { ... }
```

--------------------------------

### Creating a new Config instance

Source: https://askama.rs/en/stable/doc/src/askama_derive/config.rs.html

The `new` function initializes a `Config` instance, utilizing a static cache (`CACHE`) to store and retrieve configurations based on `OwnedConfigKey`. It handles cache lookups and inserts new configurations if not found.

```rust
impl Config {
    pub(crate) fn new(
        source: &str,
        config_path: Option<&str>,
        template_whitespace: Option<Whitespace>,
        config_span: Option<Span>,
        full_config_path: Option<PathBuf>,
    ) -> Result<&'static Config, CompileError> {
        static CACHE: ManuallyDrop<OnceLock<OnceMap<OwnedConfigKey, &'static Config>>> = ManuallyDrop::new(OnceLock::new());
        CACHE.get_or_init(OnceMap::default).get_or_try_insert(
            &ConfigKey {
                root: Cow::Owned(manifest_root()),
                source: source.into(),
                config_path: config_path.map(Cow::Borrowed),
                template_whitespace,
            },
            |key| {
                let config = Config::new_uncached(key.to_owned(), config_span, full_config_path)?;
                let config = &*Box::leak(Box::new(config));
                Ok((config._key, config))
            },
            |config| *config,
        )
    }

    fn new_uncached(
        key: OwnedConfigKey,
        config_span: Option<Span>,
        full_config_path: Option<PathBuf>,
    ) -> Result<Config, CompileError> {
        let s = key.0.source.as_ref();
        let config_path = key.0.config_path.as_deref();
        let root = key.0.root.as_ref();

        let default_dirs = vec![root.join("templates")];

        let mut syntaxes = HashMap::default();
        syntaxes.insert(DEFAULT_SYNTAX_NAME.to_string(), SyntaxAndCache::default());

        let raw = if s.is_empty() {
            RawConfig::default()
        } else {
            RawConfig::from_toml_str(s)?
        };

        let (dirs, default_syntax, whitespace) = match raw.general {
            Some(General {
                dirs,
                default_syntax,
                whitespace,
            }) => (
                dirs.map_or(default_dirs, |v| {
                    v.into_iter()
                        .flat_map(|dir| get_config_dirs(root, dir))
                        .collect()
                }),
                default_syntax.unwrap_or(DEFAULT_SYNTAX_NAME),
                whitespace,
            ),
            None => (default_dirs, DEFAULT_SYNTAX_NAME, Whitespace::default()),
        };
        let file_info = config_path.map(|path| FileInfo::new(Path::new(path), None, None));
        let whitespace = key.0.template_whitespace.unwrap_or(whitespace);

        if let Some(raw_syntaxes) = raw.syntax {
            for raw_s in raw_syntaxes {
                let name = raw_s.name;
                match syntaxes.entry(name.to_string()) {
                    Entry::Vacant(entry) => {

```

--------------------------------

### Example: JSON in `data-extra` attribute

Source: https://askama.rs/en/stable/doc/askama/filters/fn.json.html

A complete example demonstrating the `json` filter's use within a `data-extra` attribute in an HTML `<li>` tag, including the Rust struct and assertion.

```rust
/// ```jinja
/// <div><li data-extra='{{data|json|safe}}'>Example</li></div>
/// ```

#[derive(Template)]
#[template(ext = "html", in_doc = true)]
struct Example<'a> {
    data: Vec<&'a str>,
}

assert_eq!(
    Example { data: vec!["foo", "bar"] }.to_string(),
    "<div><li data-extra='[\"foo\",\"bar\"]'>Example</li></div>"
);
```

--------------------------------

### Example Usage of strip_common

Source: https://askama.rs/en/stable/doc/askama_parser/fn.strip_common.html

Illustrates how `strip_common` works by showing an example where the base path is the current directory and the target path is a file within subdirectories. The function returns the relative path from the base.

```text
current dir: /a/b/c
path:        /a/b/c/d/e.txt

`strip_common` will return `d/e.txt`.
```

--------------------------------

### Define and Render a Basic Askama Template

Source: https://askama.rs/en/stable/doc/askama/index.html

This snippet shows how to define a template using the `Template` derive macro with an inline source and render it. It demonstrates basic variable substitution and the default auto-escaping behavior.

```rust
#[derive(Template)]
#[template(
    ext = "html",
    source = "<p>© {{ year }} {{ enterprise|upper }}</p>"
)]
struct Footer<'a> {
    year: u16,
    enterprise: &'a str,
}

assert_eq!(
    Footer { year: 2025, enterprise: "<em>Askama</em> developers" }.to_string(),
    "<p>© 2025 &#60;EM&#62;ASKAMA&#60;/EM&#62; DEVELOPERS</p>",
);
// In here you see can Askama's auto-escaping. You, the developer,
// can easily disable the auto-escaping with the `|safe` filter,
// but a malicious user cannot insert e.g. HTML scripts this way.
```

--------------------------------

### Askama `format` filter example

Source: https://askama.rs/en/stable/doc/src/askama/filters/alloc.rs.html

Illustrates the `format` filter in Askama, which takes a format string as the first argument and subsequent values to be formatted. This filter is analogous to Rust's `format!()` macro and supports filter composition.

```rust
# #[cfg(feature = "code-in-doc")] {
# use askama::Template;
/// ```jinja
/// <div>{{ "{:?}"|format(value) }}</div>
/// ```
#[derive(Template)]
#[template(ext = "html", in_doc = true)]
struct Example {
    value: (usize, usize),
}

assert_eq!(
    Example { value: (3, 4) }.to_string(),
    "<div>(3, 4)</div>"
);
# }
```

--------------------------------

### Example: Using the `backdoor` filter with MaybeSafe

Source: https://askama.rs/en/stable/doc/src/askama/filters/escape.rs.html

This example demonstrates a custom filter `backdoor` that uses `MaybeSafe` to conditionally escape its output. The template uses this filter to control whether a class attribute is escaped.

```Rust
mod filters {
    use askama::{filters::MaybeSafe, Result, Values};

    // Do not actually use this filter! It's an intentionally bad example.
    #[askama::filter_fn]
    pub fn backdoor<T: std::fmt::Display>(
        s: T,
        _: &dyn Values,
        enable: &bool,
    ) -> Result<MaybeSafe<T>> {
        Ok(match *enable {
            true => MaybeSafe::Safe(s),
            false => MaybeSafe::NeedsEscaping(s),
        })
    }
}

#[derive(askama::Template)]
#[template(
    source = "<div class='{{ klass|backdoor(enable_backdoor) }}'></div>",
    ext = "html"
)]
struct DivWithBackdoor<'a> {
    klass: &'a str,
    enable_backdoor: bool,
}

assert_eq!(
    DivWithBackdoor { klass: "<script>", enable_backdoor: false }.to_string(),
    "<div class='&#60;script&#62;'></div>",
);
assert_eq!(
    DivWithBackdoor { klass: "<script>", enable_backdoor: true }.to_string(),
    "<div class='<script>'></div>",
);
```

--------------------------------

### Using format filter with multiple arguments

Source: https://askama.rs/en/stable/doc/askama/filters/fn.format.html

Demonstrates how to use the `format` filter with multiple arguments. The first argument is the format string, and subsequent arguments are the values to be formatted.

```askama
{{ "{:?}{:?}"|format(value, other_value) }}
```

--------------------------------

### AsIndent Usage Examples

Source: https://askama.rs/en/stable/doc/askama/filters/trait.AsIndent.html

Demonstrates how to use the `as_indent` method on different types. The `usize` type is shown to produce a string of spaces for indentation, while a string literal produces itself.

```rust
assert_eq!(4.as_indent(), "    ");
assert_eq!(" -> ".as_indent(), " -> ");
```

--------------------------------

### Custom Askama Filter Using MaybeSafe

Source: https://askama.rs/en/stable/doc/askama/filters/enum.MaybeSafe.html

An example of a custom Askama filter function that returns a MaybeSafe enum. This filter conditionally marks its output as safe based on an 'enable' boolean parameter. Note: This is an intentionally bad example and should not be used in production.

```rust
mod filters {
    use askama::{filters::MaybeSafe, Result, Values};

    // Do not actually use this filter! It's an intentionally bad example.
    #[askama::filter_fn]
    pub fn backdoor<T: std::fmt::Display>(
        s: T,
        _: &dyn Values,
        enable: &bool,
    ) -> Result<MaybeSafe<T>> {
        Ok(match *enable {
            true => MaybeSafe::Safe(s),
            false => MaybeSafe::NeedsEscaping(s),
        })
    }
}
```

--------------------------------

### Get length of AsciiStr

Source: https://askama.rs/en/stable/doc/src/askama_derive/ascii_str.rs.html

Returns the number of AsciiChar elements in the AsciiStr.

```rust
pub const fn len(&self) -> usize {
    self.0.len()
}
```

--------------------------------

### TryFrom Implementation Example

Source: https://askama.rs/en/stable/doc/askama_parser/node/struct.Extends.html

Demonstrates the TryFrom trait implementation for generic types.

```rust
type Error = Infallible;

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> {
    // Performs the conversion.
    // ... implementation details ...
}
```

--------------------------------

### Implement CloneToUninit for T (Nightly)

Source: https://askama.rs/en/stable/doc/askama/filters/struct.Text.html

Presents the experimental nightly-only API for `clone_to_uninit`, which performs copy-assignment to uninitialized memory.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### Get AST Nodes

Source: https://askama.rs/en/stable/doc/src/askama_parser/lib.rs.html

Returns a slice of the `Node`s contained within the `Ast`.

```rust
#[must_use]
    pub fn nodes(&self) -> &[Box<Node<'a>>] {
        &self.nodes
    }
```

--------------------------------

### Loading Configuration Directories

Source: https://askama.rs/en/stable/doc/src/askama_derive/config.rs.html

Handles the logic for determining template directories, supporting glob patterns for dynamic directory discovery when the 'config' feature is enabled.

```Rust
#[cfg(not(feature = "config"))]
fn get_config_dirs(_root: &Path, _dir: &str) -> impl Iterator<Item = PathBuf> {
    std::iter::empty()
}

#[cfg(feature = "config")]
fn get_config_dirs(root: &Path, dir: &str) -> impl Iterator<Item = PathBuf> {
    let path = root.join(dir);
    if dir.contains('*')
        && let Some(path) = path.to_str()
        && let Ok(matches) = glob::glob(path)
    {
        PathOrPaths::Paths(matches)
    } else {
        PathOrPaths::Path(Some(path))
    }
}
```

--------------------------------

### Reference and Dereference Operators

Source: https://askama.rs/en/stable/print.html

Shows how to use the '&' (reference) and '*' (dereference) operators, similar to Rust, for variables.

```askama
{% let x = &"bla" %}
{% if *x == "bla" %}
Just talking
{% else if x == &"another" %}
Another?!
{% endif %}
```

--------------------------------

### Get Original Source

Source: https://askama.rs/en/stable/doc/src/askama_parser/lib.rs.html

Returns a reference to the original source string of the template.

```rust
#[must_use]
        pub fn source(&self) -> &str {
            &self.source
        }
```

--------------------------------

### Any Trait Implementation

Source: https://askama.rs/en/stable/doc/askama_parser/struct.Syntax.html

Provides a way to get the TypeId of any type that implements 'static.

```rust
fn type_id(&self) -> TypeId

```

--------------------------------

### Default Configuration for Template Directories and Whitespace

Source: https://askama.rs/en/stable/configuration.html

This snippet shows the default configuration for Askama, specifying the directory to search for templates and preserving whitespace by default.

```toml
[general]
dirs = ["templates"]
whitespace = "preserve"

```

--------------------------------

### Get Error Source

Source: https://askama.rs/en/stable/doc/askama/enum.Error.html

Retrieves the underlying source error, if any, from the Askama `Error`.

```rust
fn source(&self) -> Option<&(dyn StdError + 'static)>
```

--------------------------------

### MapChain Get Caller Alias

Source: https://askama.rs/en/stable/doc/src/askama_derive/generator.rs.html

Searches scopes in reverse for a CallerAlias with the given key.

```rust
fn get_caller<'b>(&'b self, key: &str) -> Option<&'b LocalCallerMeta<'a>> {
    match self.scopes.iter().rev().find_map(|set| set.get(key)) {
        Some(LocalMeta::CallerAlias(caller)) => Some(caller),
        _ => None,
    }
}
```

--------------------------------

### FileInfo Display Implementation

Source: https://askama.rs/en/stable/doc/src/askama_derive/lib.rs.html

Implements `fmt::Display` for `FileInfo` to format the file path and error context. It handles alternate formatting and includes source code context when available.

```rust
impl fmt::Display for FileInfo<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if !f.alternate() {
            f.write_str("\n  --> ")?;
        }
        if let (Some(source), Some(node_source)) = (self.source, self.node_source) {
            let (error_info, file_path) = generate_error_info(source, node_source, self.path);
            write!(
                f,
                "{file_path}:{row}:{column}",
                row = error_info.row,
                column = error_info.column,
            )?;
            if !f.alternate() {
                write!(
                    f,
                    "\n{source_after}",
                    source_after = error_info.source_after,
                )?;
            }
            Ok(())
        } else {
            write!(
                f,
                "{}",
                match std::env::current_dir() {
                    Ok(cwd) => fmt_left!(move "{}", strip_common(&cwd, self.path)),
                    Err(_) => fmt_right!("{}", self.path.display()),
                }
            )
        }
    }
}
```

--------------------------------

### Whitespace Suppression Example

Source: https://askama.rs/en/stable/configuration.html

Illustrates how whitespace is suppressed before or after a block when the `whitespace` configuration is set to `suppress`.

```toml
[general]
whitespace = "suppress"

```

--------------------------------

### Macro with Type Annotations

Source: https://askama.rs/en/stable/template_syntax.html

Shows how to add type annotations to macro arguments, including optional types and default values. The example uses 'Option<u32>' for arguments.

```askama
{%- macro test(value: Option<u32>, extra: Option<u32> = None) -%}
  {% if let Some(value) = value -%}value is {{value}}{% endif -%}
  {% if let Some(extra) = title -%}extra is {{extra}}{% endif -%}
{% endmacro -%}
```

--------------------------------

### Safely Unwrapping Ok Value (Nightly)

Source: https://askama.rs/en/stable/doc/askama/type.Result.html

Demonstrates the experimental `into_ok` method, which returns the Ok value without panicking. This API is intended as a compile-time safeguard against Results that are guaranteed to be Ok.

```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

--------------------------------

### Get Config Path

Source: https://askama.rs/en/stable/doc/src/askama_derive/input.rs.html

A simple getter method to retrieve the configuration path from the template arguments.

```rust
    pub(crate) fn config_path(&self) -> Option<&str> {
        self.config.as_deref()
    }

```

--------------------------------

### MapChain Get Local Variable

Source: https://askama.rs/en/stable/doc/src/askama_derive/generator.rs.html

Searches scopes in reverse for a local variable with the given key.

```rust
fn get<'b>(&'b self, key: &str) -> Option<&'b LocalVariableMeta> {
    match self.scopes.iter().rev().find_map(|set| set.get(key)) {
        Some(LocalMeta::Variable(var)) => Some(var),
        _ => None,
    }
}
```

--------------------------------

### Read Configuration File

Source: https://askama.rs/en/stable/doc/src/askama_derive/config.rs.html

Reads the content of a configuration file from a given path or the default 'askama.toml'. Returns the file content and its canonicalized path, or an error if the file cannot be read or does not exist.

```rust
pub(crate) fn read_config_file(
        config_path: Option<&str>,
        span: Option<Span>,
    ) -> Result<(String, Option<PathBuf>), CompileError> {
        let root = manifest_root();
        let filename = match config_path {
            Some(config_path) => root.join(config_path),
            None => root.join(CONFIG_FILE_NAME),
        };

        if filename.exists() {
            let content = fs::read_to_string(&filename).map_err(|err| {
                CompileError::no_file_info(
                    format_args!("unable to read {}: {err}", filename.display()),
                    span,
                )
            })?;
            Ok((content, filename.canonicalize().ok()))
        } else if config_path.is_some() {
            Err(CompileError::no_file_info(
                format_args!("`{}` does not exist", filename.display()),
                span,
            ))
        } else {
            Ok((String::new(), None))
        }
    }
```

--------------------------------

### Parse Separated Digits

Source: https://askama.rs/en/stable/doc/src/askama_parser/lib.rs.html

Creates a parser for underscore-separated digits in a given radix. Optionally starts with an underscore.

```Rust
fn separated_digits<'a: 'l, 'l>(
    radix: u32,
    start: bool,
) -> impl ModalParser<InputStream<'a, 'l>, &'a str, ErrorContext> {
    (
        cond(!start, repeat(0.., '_').map(|()| ())),
        one_of(move |ch: char| ch.is_digit(radix)),
        repeat(0.., one_of(move |ch: char| ch == '_' || ch.is_digit(radix))).map(|()| ()),
    )
        .take()
}

```

--------------------------------

### WithSpan<&str>::start()

Source: https://askama.rs/en/stable/doc/src/askama_parser/lib.rs.html

Returns an empty WithSpan<&str> at the start of the contained string's span.

```rust
pub fn start(self) -> Self {
    let (inner, span) = self.deconstruct();
    Self::new(&inner[..0], span.start())
}
```

--------------------------------

### into_ok

Source: https://askama.rs/en/stable/doc/askama/type.Result.html

Returns the contained Ok value, but never panics. This is a nightly-only experimental API.

```APIDOC
## into_ok

### Description
Returns the contained `Ok` value, but never panics. Unlike `unwrap`, this method is known to never panic on the result types it is implemented for. Therefore, it can be used instead of `unwrap` as a maintainability safeguard that will fail to compile if the error type of the `Result` is later changed to an error that can actually occur.

### Experimental
This is a nightly-only experimental API.

### Method Signature
`pub fn into_ok(self) -> T`

### Type Parameters
`E: Into<!>`

### Examples
```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```
```

--------------------------------

### Example of default pluralization

Source: https://askama.rs/en/stable/doc/src/askama/filters/core.rs.html

Demonstrates the default behavior of the `pluralize` filter where 's' is appended for plural forms.

```jinja
I have {{dogs}} dog{{dogs|pluralize}} and {{cats}} cat{{cats|pluralize}}.
```

--------------------------------

### Applying Filters to Blocks

Source: https://askama.rs/en/stable/template_syntax.html

Demonstrates using filter blocks to apply filters like `lower` to an entire block of template content.

```askama
{% filter lower %}
  {{ t }} / HELLO / {{ u }}
{% endfilter %}

```

--------------------------------

### PrimitiveType Implementations

Source: https://askama.rs/en/stable/doc/askama/trait.PrimitiveType.html

Examples of how the PrimitiveType trait is implemented for various primitive types and common smart pointers.

```APIDOC
## Implementations on Foreign Types

### impl PrimitiveType for bool
- type Value = bool
- fn get(&self) -> Self::Value

### impl PrimitiveType for f32
- type Value = f32
- fn get(&self) -> Self::Value

### impl PrimitiveType for f64
- type Value = f64
- fn get(&self) -> Self::Value

### impl PrimitiveType for i8
- type Value = i8
- fn get(&self) -> Self::Value

### impl PrimitiveType for i16
- type Value = i16
- fn get(&self) -> Self::Value

### impl PrimitiveType for i32
- type Value = i32
- fn get(&self) -> Self::Value

### impl PrimitiveType for i64
- type Value = i64
- fn get(&self) -> Self::Value

### impl PrimitiveType for i128
- type Value = i128
- fn get(&self) -> Self::Value

### impl PrimitiveType for isize
- type Value = isize
- fn get(&self) -> Self::Value

### impl PrimitiveType for u8
- type Value = u8
- fn get(&self) -> Self::Value

### impl PrimitiveType for u16
- type Value = u16
- fn get(&self) -> Self::Value

### impl PrimitiveType for u32
- type Value = u32
- fn get(&self) -> Self::Value

### impl PrimitiveType for u64
- type Value = u64
- fn get(&self) -> Self::Value

### impl PrimitiveType for u128
- type Value = u128
- fn get(&self) -> Self::Value

### impl PrimitiveType for usize
- type Value = usize
- fn get(&self) -> Self::Value

### impl PrimitiveType for NonZeroI8
- type Value = i8
- fn get(&self) -> Self::Value

### impl PrimitiveType for NonZeroI16
- type Value = i16
- fn get(&self) -> Self::Value

### impl PrimitiveType for NonZeroI32
- type Value = i32
- fn get(&self) -> Self::Value

### impl PrimitiveType for NonZeroI64
- type Value = i64
- fn get(&self) -> Self::Value

### impl PrimitiveType for NonZeroI128
- type Value = i128
- fn get(&self) -> Self::Value

### impl PrimitiveType for NonZeroIsize
- type Value = isize
- fn get(&self) -> Self::Value

### impl PrimitiveType for NonZeroU8
- type Value = u8
- fn get(&self) -> Self::Value

### impl PrimitiveType for NonZeroU16
- type Value = u16
- fn get(&self) -> Self::Value

### impl PrimitiveType for NonZeroU32
- type Value = u32
- fn get(&self) -> Self::Value

### impl PrimitiveType for NonZeroU64
- type Value = u64
- fn get(&self) -> Self::Value

### impl PrimitiveType for NonZeroU128
- type Value = u128
- fn get(&self) -> Self::Value

### impl PrimitiveType for NonZeroUsize
- type Value = usize
- fn get(&self) -> Self::Value

### impl<T> PrimitiveType for Pin<T>
where T: Deref, <T as Deref>::Target: PrimitiveType
- type Value = <<T as Deref>::Target as PrimitiveType>::Value
- fn get(&self) -> Self::Value

### impl<T: PrimitiveType + Copy> PrimitiveType for Cell<T>
- type Value = <T as PrimitiveType>::Value
- fn get(&self) -> Self::Value

### impl<T: PrimitiveType + ?Sized> PrimitiveType for &T
- type Value = <T as PrimitiveType>::Value
- fn get(&self) -> Self::Value

### impl<T: PrimitiveType + ?Sized> PrimitiveType for &mut T
- type Value = <T as PrimitiveType>::Value
- fn get(&self) -> Self::Value

### impl<T: PrimitiveType + ?Sized> PrimitiveType for Box<T>
- type Value = <T as PrimitiveType>::Value
- fn get(&self) -> Self::Value

### impl<T: PrimitiveType + ?Sized> PrimitiveType for Rc<T>
- type Value = <T as PrimitiveType>::Value
- fn get(&self) -> Self::Value

### impl<T: PrimitiveType + ?Sized> PrimitiveType for Arc<T>
- type Value = <T as PrimitiveType>::Value
- fn get(&self) -> Self::Value
```

--------------------------------

### Instantiating Structs in Askama

Source: https://askama.rs/en/stable/template_syntax.html

Create struct instances directly within Askama templates, similar to Rust syntax. Supports field initialization and base struct instantiation.

```askama
{{ MyStruct { field1: 1, field2: "foo" }.to_string() }}

{{ MyStruct { field1: 1, ..other_struct } }}
{{ MyStruct { field1: 1, ..Default::default() } }}
```

--------------------------------

### Askama `fmt` filter example

Source: https://askama.rs/en/stable/doc/src/askama/filters/alloc.rs.html

Demonstrates the `fmt` filter in Askama, which applies a format string to a value. The format string is the second argument, and the value is the first. This is useful for controlling the output of variables within templates.

```rust
# #[cfg(feature = "code-in-doc")] {
# use askama::Template;
/// ```jinja
/// <div>{{ value|fmt("{:?}") }}</div>
/// ```
#[derive(Template)]
#[template(ext = "html", in_doc = true)]
struct Example {
    value: (usize, usize),
}

assert_eq!(
    Example { value: (3, 4) }.to_string(),
    "<div>(3, 4)</div>"
);
# }
```

--------------------------------

### Getting Span from PartialTemplateArgsSource

Source: https://askama.rs/en/stable/doc/src/askama_derive/input.rs.html

Implements a method to retrieve the source code span for different variants of PartialTemplateArgsSource.

```rust
impl PartialTemplateArgsSource {
    pub(crate) fn span(&self) -> Span {
        match self {
            #[cfg(feature = "external-sources")]
            Self::Path(s) => s.span(),
            Self::Source(s) => s.span(),
            #[cfg(feature = "code-in-doc")]
            Self::InDoc(s, _) => s.span(),
        }
    }
}
```

--------------------------------

### MapChain Get Any Local

Source: https://askama.rs/en/stable/doc/src/askama_derive/generator.rs.html

Searches scopes in reverse for any local entry (except negative) with the given key.

```rust
fn get_any<'b>(&'b self, key: &str) -> Option<&'b LocalMeta<'a>> {
    match self.scopes.iter().rev().find_map(|set| set.get(key)) {
        Some(LocalMeta::Negative) => None,
        Some(local) => Some(local),
        _ => None,
    }
}
```

--------------------------------

### Using the fmt filter

Source: https://askama.rs/en/stable/doc/askama/filters/fn.fmt.html

Demonstrates how to use the `fmt` filter to format a value within an Askama template. The format string must be a string literal.

```askama
{{ value|fmt("{:?}") }}
```

--------------------------------

### Get Ast Nodes

Source: https://askama.rs/en/stable/doc/askama_parser/struct.Ast.html

Retrieves a slice of boxed Node elements representing the AST's structure.

```rust
pub fn nodes(&self) -> &[Box<Node<'a>>]
```