MiniJinja 模板引擎

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 already existing ecosystem of editor integrations.
https://docs.rs/minijinja/latest/minijinja

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

You can play with MiniJinja online in the browser playground powered by a WASM build of MiniJinja. https://mitsuhiko.github.io/minijinja-playground/

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());

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.

Custom Filters

MiniJinja lets you register functions as filter functions (see Function) with the engine. These can then be invoked directly from the template:

use minijinja::{Environment, context};

let mut env = Environment::new();
env.add_filter("repeat", str::repeat);
env.add_template("hello", "{{ 'Na '|repeat(3) }} {{ name }}!").unwrap();
let tmpl = env.get_template("hello").unwrap();
println!("{}", tmpl.render(context!(name => "Batman")).unwrap());

Na Na Na Batman!

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.

• For auto reloading use the minijinja-autoreload crate.

• For simpler embedding of templates use the minijinja-embed crate.

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

Error Handling

MiniJinja tries to give you good errors out of the box. However if you use includes or template inheritance your experience will improve greatly if you ensure to render chained errors. For more information see Error with an example.

Size and Compile Times

MiniJinja attempts to compile fast so it can be used as a sensible template engine choice when compile times matter. Because of this it’s internally modular so unnecessary bits and pieces can be removed. The default set of features tries to strike a balance but in situations where only a subset is needed (eg: build.rs) all default features can be be disabled.

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.