Merge pull request #725 from GuillaumeGomez/custom-escaper

GuillaumeGomez · web-flow · commit 46cd48b56c79 · 2026-04-11T14:48:06.000+02:00
Add custom escaper example
diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
@@ -30,7 +30,7 @@ jobs:
       - run: |
           set -eu
           for PKG in \
-            bench-build examples/actix-web-app examples/axum-app examples/poem-app examples/rocket-app examples/warp-app fuzzing \
+            bench-build examples/actix-web-app examples/axum-app examples/poem-app examples/rocket-app examples/warp-app examples/custom-escaper fuzzing \
             askama askama_derive askama_escape askama_macros askama_parser \
             testing testing-alloc testing-no-std testing-renamed
           do
@@ -129,7 +129,7 @@ jobs:
           cargo sort --check --check-format --grouped
           set -eu
           for PKG in \
-            bench-build examples/actix-web-app examples/axum-app examples/poem-app examples/rocket-app examples/warp-app fuzzing \
+            bench-build examples/actix-web-app examples/axum-app examples/poem-app examples/rocket-app examples/warp-app examples/custom-escaper fuzzing \
             askama askama_derive askama_escape askama_macros askama_parser \
             testing testing-alloc testing-no-std testing-renamed
           do
@@ -171,7 +171,7 @@ jobs:
     strategy:
       matrix:
         package: [
-          bench-build, examples/actix-web-app, examples/axum-app, examples/poem-app, examples/rocket-app, examples/warp-app, fuzzing,
+          bench-build, examples/actix-web-app, examples/axum-app, examples/poem-app, examples/rocket-app, examples/warp-app, examples/custom-escaper, fuzzing,
           askama, askama_derive, askama_escape, askama_macros, askama_parser,
           testing, testing-alloc, testing-no-std, testing-renamed,
         ]
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 # askama
 
 [![Crates.io](https://img.shields.io/crates/v/askama?logo=rust&style=flat-square&logoColor=white "Crates.io")](https://crates.io/crates/askama)
-[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/askama-rs/askama/rust.yml?branch=master&logo=github&style=flat-square&logoColor=white "GitHub Workflow Status")](https://github.com/askama-rs/askama/actions/workflows/rust.yml)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/askama-rs/askama/rust.yml?branch=main&logo=github&style=flat-square&logoColor=white "GitHub Workflow Status")](https://github.com/askama-rs/askama/actions/workflows/rust.yml)
 [![Book](https://img.shields.io/readthedocs/askama?label=book&logo=readthedocs&style=flat-square&logoColor=white "Book")](https://askama.rs/)
 [![docs.rs](https://img.shields.io/docsrs/askama?logo=docsdotrs&style=flat-square&logoColor=white "docs.rs")](https://docs.rs/askama/)
 
diff --git a/askama/src/lib.rs b/askama/src/lib.rs
@@ -1,5 +1,5 @@
 //! [![Crates.io](https://img.shields.io/crates/v/askama?logo=rust&style=flat-square&logoColor=white "Crates.io")](https://crates.io/crates/askama)
-//! [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/askama-rs/askama/rust.yml?branch=master&logo=github&style=flat-square&logoColor=white "GitHub Workflow Status")](https://github.com/askama-rs/askama/actions/workflows/rust.yml)
+//! [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/askama-rs/askama/rust.yml?branch=main&logo=github&style=flat-square&logoColor=white "GitHub Workflow Status")](https://github.com/askama-rs/askama/actions/workflows/rust.yml)
 //! [![Book](https://img.shields.io/readthedocs/askama?label=book&logo=readthedocs&style=flat-square&logoColor=white "Book")](https://askama.rs/)
 //! [![docs.rs](https://img.shields.io/docsrs/askama?logo=docsdotrs&style=flat-square&logoColor=white "docs.rs")](https://docs.rs/askama/)
 //!
@@ -10,7 +10,7 @@
 //! in [`askama_macros`](https://crates.io/crates/askama_macros)).
 //!
 //! For feature highlights and a quick start, please review the
-//! [README](https://github.com/askama-rs/askama/blob/master/README.md).
+//! [README](https://github.com/askama-rs/askama/blob/main/README.md).
 //!
 //! You can find the documentation about our syntax, features, configuration in our book:
 //! [askama.rs](https://askama.rs/).
diff --git a/askama_derive/README.md b/askama_derive/README.md
@@ -1,7 +1,7 @@
 # askama_derive: code generator of Askama templating engine
 
 [![Crates.io](https://img.shields.io/crates/v/askama_derive?logo=rust&style=flat-square&logoColor=white "Crates.io")](https://crates.io/crates/askama_derive)
-[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/askama-rs/askama/rust.yml?branch=master&logo=github&style=flat-square&logoColor=white "GitHub Workflow Status")](https://github.com/askama-rs/askama/actions/workflows/rust.yml)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/askama-rs/askama/rust.yml?branch=main&logo=github&style=flat-square&logoColor=white "GitHub Workflow Status")](https://github.com/askama-rs/askama/actions/workflows/rust.yml)
 [![Book](https://img.shields.io/readthedocs/askama?label=book&logo=readthedocs&style=flat-square&logoColor=white "Book")](https://askama.rs/)
 [![docs.rs](https://img.shields.io/docsrs/askama_derive?logo=docsdotrs&style=flat-square&logoColor=white "docs.rs")](https://docs.rs/askama_derive/)
 
diff --git a/askama_escape/README.md b/askama_escape/README.md
@@ -1,7 +1,7 @@
 # askama_escape: HTML escaping, extracted from [Askama](https://askama.rs/)
 
 [![Crates.io](https://img.shields.io/crates/v/askama_escape?logo=rust&style=flat-square&logoColor=white "Crates.io")](https://crates.io/crates/askama_escape)
-[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/askama-rs/askama/rust.yml?branch=master&logo=github&style=flat-square&logoColor=white "GitHub Workflow Status")](https://github.com/askama-rs/askama/actions/workflows/rust.yml)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/askama-rs/askama/rust.yml?branch=main&logo=github&style=flat-square&logoColor=white "GitHub Workflow Status")](https://github.com/askama-rs/askama/actions/workflows/rust.yml)
 [![docs.rs](https://img.shields.io/docsrs/askama_escape?logo=docsdotrs&style=flat-square&logoColor=white "docs.rs")](https://docs.rs/askama_escape/)
 
 Useful if you don't need a template engine, but if you need to escape a text for HTML or XML.
diff --git a/askama_macros/README.md b/askama_macros/README.md
@@ -1,7 +1,7 @@
 # askama_macros: procedural macros for the Askama templating engine
 
 [![Crates.io](https://img.shields.io/crates/v/askama_macros?logo=rust&style=flat-square&logoColor=white "Crates.io")](https://crates.io/crates/askama_macros)
-[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/askama-rs/askama/rust.yml?branch=master&logo=github&style=flat-square&logoColor=white "GitHub Workflow Status")](https://github.com/askama-rs/askama/actions/workflows/rust.yml)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/askama-rs/askama/rust.yml?branch=main&logo=github&style=flat-square&logoColor=white "GitHub Workflow Status")](https://github.com/askama-rs/askama/actions/workflows/rust.yml)
 [![Book](https://img.shields.io/readthedocs/askama?label=book&logo=readthedocs&style=flat-square&logoColor=white "Book")](https://askama.rs/)
 [![docs.rs](https://img.shields.io/docsrs/askama_macros?logo=docsdotrs&style=flat-square&logoColor=white "docs.rs")](https://docs.rs/askama_macros/)
 
diff --git a/askama_parser/README.md b/askama_parser/README.md
@@ -1,7 +1,7 @@
 # askama_parser: template parser for the Askama templating engine
 
 [![Crates.io](https://img.shields.io/crates/v/askama_parser?logo=rust&style=flat-square&logoColor=white "Crates.io")](https://crates.io/crates/askama_parser)
-[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/askama-rs/askama/rust.yml?branch=master&logo=github&style=flat-square&logoColor=white "GitHub Workflow Status")](https://github.com/askama-rs/askama/actions/workflows/rust.yml)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/askama-rs/askama/rust.yml?branch=main&logo=github&style=flat-square&logoColor=white "GitHub Workflow Status")](https://github.com/askama-rs/askama/actions/workflows/rust.yml)
 [![Book](https://img.shields.io/readthedocs/askama?label=book&logo=readthedocs&style=flat-square&logoColor=white "Book")](https://askama.rs/)
 [![docs.rs](https://img.shields.io/docsrs/askama_parser?logo=docsdotrs&style=flat-square&logoColor=white "docs.rs")](https://docs.rs/askama_parser/)
 
diff --git a/askama_parser/benches/librustdoc/LICENSE.md b/askama_parser/benches/librustdoc/LICENSE.md
@@ -3,5 +3,5 @@ eeb59f16a5f40e14dc29b95155b7f2569329e3ec. Dual licensed under MIT OR Apache-2.0.
 
 Please find the authors in [their Git history].
 
-[librustdoc/html/templates]: <https://github.com/rust-lang/rust/tree/master/src/librustdoc/html/templates>
-[their Git history]: <https://github.com/rust-lang/rust/commits/master/src/librustdoc/html/templates>
+[librustdoc/html/templates]: <https://github.com/rust-lang/rust/tree/main/src/librustdoc/html/templates>
+[their Git history]: <https://github.com/rust-lang/rust/commits/main/src/librustdoc/html/templates>
diff --git a/book/book.toml b/book/book.toml
@@ -8,6 +8,6 @@ title = "Askama"
 edition = "2021"
 
 [output.html]
-git-repository-url = "https://github.com/askama-rs/askama/tree/master/book"
-edit-url-template = "https://github.com/askama-rs/askama/tree/master/book/{path}"
+git-repository-url = "https://github.com/askama-rs/askama/tree/main/book"
+edit-url-template = "https://github.com/askama-rs/askama/tree/main/book/{path}"
 playground.runnable = false
diff --git a/book/src/configuration.md b/book/src/configuration.md
@@ -151,4 +151,7 @@ extensions = ["js"]
 [`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.
+
 [`Escaper`]: https://docs.rs/askama/latest/askama/filters/trait.Escaper.html
+[custom escaper example]: https://github.com/askama-rs/askama/tree/main/examples/warp-app
diff --git a/book/src/frameworks.md b/book/src/frameworks.md
@@ -39,7 +39,7 @@ e.g. because you know that your templates won't have rendering errors, then usin
 [![our actix-web example web-app](
     https://img.shields.io/badge/actix--web-example-informational?style=flat-square&logo=git&logoColor=white&color=%23228b22
 )](
-    https://github.com/askama-rs/askama/tree/master/examples/actix-web-app "our actix-web example web-app"
+    https://github.com/askama-rs/askama/tree/main/examples/actix-web-app "our actix-web example web-app"
 )
 [![crates.io: actix-web](
     https://img.shields.io/crates/v/actix-web?label=actix-web&style=flat-square&logo=rust&logoColor=white&color=informational
@@ -107,7 +107,7 @@ impl Responder for AppError {
 [![our axum example web-app](
     https://img.shields.io/badge/axum-example-informational?style=flat-square&logo=git&logoColor=white&color=%23228b22
 )](
-    https://github.com/askama-rs/askama/tree/master/examples/axum-app "our axum example web-app"
+    https://github.com/askama-rs/askama/tree/main/examples/axum-app "our axum example web-app"
 )
 [![crates.io: axum](
     https://img.shields.io/crates/v/axum?label=axum&style=flat-square&logo=rust&logoColor=white&color=informational
@@ -163,7 +163,7 @@ impl IntoResponse for AppError {
 [![our poem example web-app](
     https://img.shields.io/badge/poem-example-informational?style=flat-square&logo=git&logoColor=white&color=%23228b22
 )](
-    https://github.com/askama-rs/askama/tree/master/examples/poem-app "our poem example web-app"
+    https://github.com/askama-rs/askama/tree/main/examples/poem-app "our poem example web-app"
 )
 [![crates.io: poem](
     https://img.shields.io/crates/v/poem?label=poem&style=flat-square&logo=rust&logoColor=white&color=informational
@@ -229,7 +229,7 @@ impl IntoResponse for AppError {
 [![our rocket example web-app](
     https://img.shields.io/badge/rocket-example-informational?style=flat-square&logo=git&logoColor=white&color=%23228b22
 )](
-    https://github.com/askama-rs/askama/tree/master/examples/rocket-app "our rocket example web-app"
+    https://github.com/askama-rs/askama/tree/main/examples/rocket-app "our rocket example web-app"
 )
 [![crates.io: rocket](
     https://img.shields.io/crates/v/rocket?label=rocket&style=flat-square&logo=rust&logoColor=white&color=informational
@@ -294,7 +294,7 @@ impl<'r> Responder<'r, 'static> for AppError {
 [![our warp example web-app](
     https://img.shields.io/badge/warp-example-informational?style=flat-square&logo=git&logoColor=white&color=%23228b22
 )](
-    https://github.com/askama-rs/askama/tree/master/examples/warp-app "our warp example web-app"
+    https://github.com/askama-rs/askama/tree/main/examples/warp-app "our warp example web-app"
 )
 [![crates.io: warp](
     https://img.shields.io/crates/v/warp?label=warp&style=flat-square&logo=rust&logoColor=white&color=informational
diff --git a/book/src/template_syntax.md b/book/src/template_syntax.md
@@ -923,7 +923,7 @@ impl askama::filters::HtmlSafe for SectionOne<'_> {}
 ```
 
 See the example
-[render in place](https://github.com/askama-rs/askama/blob/master/testing/tests/render_in_place.rs), which demonstrates using a vector of templates in a for block.
+[render in place](https://github.com/askama-rs/askama/blob/main/testing/tests/render_in_place.rs), which demonstrates using a vector of templates in a for block.
 
 ## Comments
 
diff --git a/examples/custom-escaper/Cargo.toml b/examples/custom-escaper/Cargo.toml
@@ -0,0 +1,14 @@
+[package]
+name = "custom-escaper"
+version = "0.0.0"
+edition = "2024"
+license = "MIT OR Apache-2.0"
+publish = false
+
+# In a real application you would not need this section. It is only used in here, so that this
+# example can have a more lenient MSRV (minimum supported rust version) than askama as a whole.
+[workspace]
+members = ["."]
+
+[dependencies]
+askama = { path = "../../askama" }
diff --git a/examples/custom-escaper/README.md b/examples/custom-escaper/README.md
@@ -0,0 +1,21 @@
+# custom-escaper
+
+This example demonstrates how to add a custom escaper and its associated extension.
+
+First, create an `askama.toml` file containing:
+
+```toml
+[[escaper]]
+path = "crate::Upper"
+extensions = ["upper"]
+```
+
+`path` is where the type implementing the `askama::Escaper` trait is located (can be in
+your crate or in a dependency, it's a `use` path).
+
+`extensions` matches the template file extension or the `ext` field in the `template`
+attribute.
+
+
+Then in `src/main.rs`, you can see the implementation of the `askama::Escaper` trait on
+the `Upper` type.
diff --git a/examples/custom-escaper/askama.toml b/examples/custom-escaper/askama.toml
@@ -0,0 +1,3 @@
+[[escaper]]
+path = "crate::Upper"
+extensions = ["upper"]
diff --git a/examples/custom-escaper/src/main.rs b/examples/custom-escaper/src/main.rs
@@ -0,0 +1,36 @@
+use std::fmt;
+
+use askama::Template;
+use askama::filters::Escaper;
+
+#[derive(Template)]
+#[template(source = "name: {{name}}", ext = "upper")]
+struct Foo {
+    name: &'static str,
+}
+
+#[derive(Clone, Copy)]
+struct Upper;
+
+impl Escaper for Upper {
+    fn write_escaped_str<W: fmt::Write>(&self, mut dest: W, string: &str) -> fmt::Result {
+        dest.write_str(string.to_uppercase().as_str())
+    }
+
+    fn write_escaped_char<W: fmt::Write>(&self, mut dest: W, c: char) -> fmt::Result {
+        for upper in c.to_uppercase() {
+            dest.write_char(upper)?;
+        }
+        Ok(())
+    }
+}
+
+fn main() {
+    let rendered = Foo {
+        name: "George Name",
+    }
+    .render()
+    .unwrap();
+    assert_eq!(&rendered, "name: GEORGE NAME");
+    println!("{rendered}");
+}
