third_party/rust/askama/README.md

   1 # Askama
   2
   3 [![Documentation](https://docs.rs/askama/badge.svg)](https://docs.rs/askama/)
   4 [![Latest version](https://img.shields.io/crates/v/askama.svg)](https://crates.io/crates/askama)
   5 [![Build Status](https://github.com/djc/askama/workflows/CI/badge.svg)](https://github.com/djc/askama/actions?query=workflow%3ACI)
   6 [![Chat](https://badges.gitter.im/gitterHQ/gitter.svg)](https://gitter.im/djc/askama)
   7
   8 Askama implements a template rendering engine based on [Jinja](https://jinja.palletsprojects.com/).
   9 It generates Rust code from your templates at compile time
  10 based on a user-defined `struct` to hold the template's context.
  11 See below for an example, or read [the book][docs].
  12
  13 **"Pretty exciting. I would love to use this already."** --
  14 [Armin Ronacher][mitsuhiko], creator of Jinja
  15
  16 All feedback welcome. Feel free to file bugs, requests for documentation and
  17 any other feedback to the [issue tracker][issues] or [tweet me][twitter].
  18
  19 Askama was created by and is maintained by Dirkjan Ochtman. If you are in a
  20 position to support ongoing maintenance and further development or use it
  21 in a for-profit context, please consider supporting my open source work on
  22 [Patreon][patreon].
  23
  24 ### Feature highlights
  25
  26 * Construct templates using a familiar, easy-to-use syntax
  27 * Benefit from the safety provided by Rust's type system
  28 * Template code is compiled into your crate for [optimal performance][benchmarks]
  29 * Optional built-in support for Actix, Axum, Gotham, Mendes, Rocket, tide, and warp web frameworks
  30 * Debugging features to assist you in template development
  31 * Templates must be valid UTF-8 and produce UTF-8 when rendered
  32 * IDE support available in [JetBrains products](https://plugins.jetbrains.com/plugin/16591-askama-template-support)
  33 * Works on stable Rust
  34
  35 ### Supported in templates
  36
  37 * Template inheritance
  38 * Loops, if/else statements and include support
  39 * Macro support
  40 * Variables (no mutability allowed)
  41 * Some built-in filters, and the ability to use your own
  42 * Whitespace suppressing with '-' markers
  43 * Opt-out HTML escaping
  44 * Syntax customization
  45
  46 [docs]: https://djc.github.io/askama/
  47 [fafhrd91]: https://github.com/fafhrd91
  48 [mitsuhiko]: http://lucumr.pocoo.org/
  49 [issues]: https://github.com/djc/askama/issues
  50 [twitter]: https://twitter.com/djco/
  51 [patreon]: https://www.patreon.com/dochtman
  52 [benchmarks]: https://github.com/djc/template-benchmarks-rs
  53
  54
  55 How to get started
  56 ------------------
  57
  58 First, add the following to your crate's `Cargo.toml`:
  59
  60 ```toml
  61 # in section [dependencies]
  62 askama = "0.11.2"
  63
  64 ```
  65
  66 Now create a directory called `templates` in your crate root.
  67 In it, create a file called `hello.html`, containing the following:
  68
  69 ```
  70 Hello, {{ name }}!
  71 ```
  72
  73 In any Rust file inside your crate, add the following:
  74
  75 ```rust
  76 use askama::Template; // bring trait in scope
  77
  78 #[derive(Template)] // this will generate the code...
  79 #[template(path = "hello.html")] // using the template in this path, relative
  80                                  // to the `templates` dir in the crate root
  81 struct HelloTemplate<'a> { // the name of the struct can be anything
  82     name: &'a str, // the field name should match the variable name
  83                    // in your template
  84 }
  85
  86 fn main() {
  87     let hello = HelloTemplate { name: "world" }; // instantiate your struct
  88     println!("{}", hello.render().unwrap()); // then render it.
  89 }
  90 ```
  91
  92 You should now be able to compile and run this code.
  93
  94 Review the [test cases] for more examples.
  95
  96 [test cases]: https://github.com/djc/askama/tree/main/testing