Crate minijinja

Expand description

MiniJinja: a powerful template engine for Rust with minimal dependencies

MiniJinja is a powerful but minimal dependency template engine for Rust which is based on the syntax and behavior of the Jinja2 template engine for Python. It’s implemented on top of serde. The goal is to be able to render a large chunk of the Jinja2 template ecosystem from Rust with a minimal engine and to leverage an alredy existing ecosystem of editor integrations.

{% for user in users %}
  <li>{{ user.name }}</li>
{% endfor %}

Why MiniJinja

MiniJinja by its name wants to be a good default choice if you need a little bit of templating with minimal dependencies. It has the following goals:

Well documented, compact API
Minimal dependencies, reasonable compile times and decent runtime performance
Stay close as possible to Jinja2
Support for expression evaluation
Support for all serde compatible types
Excellent test coverage
Support for dynamic runtime objects with methods and dynamic attributes

Template Usage

To use MiniJinja one needs to create an Environment and populate it with templates. Afterwards templates can be loaded and rendered. To pass data one can pass any serde serializable value. The context! macro can be used to quickly construct a template context:

use minijinja::{Environment, context};

let mut env = Environment::new();
env.add_template("hello", "Hello {{ name }}!").unwrap();
let tmpl = env.get_template("hello").unwrap();
println!("{}", tmpl.render(context!(name => "John")).unwrap());

Hello John!

For super trivial cases where you need to render a string once, you can also use the render! macro which acts a bit like a replacement for the format! macro.

Expression Usage

MiniJinja — like Jinja2 — allows to be used as expression language. This can be useful to express logic in configuration files or similar things. For this purpose the Environment::compile_expression method can be used. It returns an expression object that can then be evaluated, returning the result:

use minijinja::{Environment, context};

let env = Environment::new();
let expr = env.compile_expression("number < 42").unwrap();
let result = expr.eval(context!(number => 23)).unwrap();
assert_eq!(result.is_true(), true);

This becomes particularly powerful when dynamic objects are exposed to templates.

Learn more

Environment: the main API entry point. Teaches you how to configure the environment.
Template: the template object API. Shows you how templates can be rendered.
syntax: provides documentation of the template engine syntax.
filters: teaches you how to write custom filters and to see the list of built-in filters.
tests: teaches you how to write custom test functions and to see the list of built-in tests.
functions: teaches how to write custom functions and to see the list of built-in functions.

Additionally there is an list of examples with many different small example programs on GitHub to explore.

Optional Features

MiniJinja comes with a lot of optional features, some of which are turned on by default. If you plan on using MiniJinja in a library, please consider turning off all default features and to opt-in explicitly into the ones you actually need.

Configurable Features

There are some additional features that can be enabled:

source: enables the Source type which helps with dynamic loading of templates.
v_htmlescape: enables the v_htmlescape dependency which implements a faster HTML escaping algorithm.
speedups: enables all speedups (currently v_htmlescape)
unstable_machinery: provides access to the internal machinery of the engine. This is a forever unstable API which mainly exists to aid debugging complex issues.
json: When enabled the tojson filter is added as builtin filter as well as the ability to auto escape via AutoEscape::Json.
urlencode: When enabled the urlencode filter is added as builtin filter.
preserve_order: When enable the internal value implementation uses an indexmap which preserves the original order of maps and structs.

Additionally to cut down on size of the engine some default functionality can be removed:

builtins: if this feature is removed the default filters, tests and functions are not implemented.
debug: if this feature is removed some debug functionality of the engine is removed as well. This mainly affects the quality of error reporting.
key_interning: if this feature is removed the automatic string interning in the value type is disabled. The default behavior can cut down on the memory consumption of the value type by interning all string keys used in values.
deserialization: when removed this disables deserialization support for the Value type.