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 and only has it as a single required
dependency. It supports a range of features from Jinja2
including inheritance, filters and more. The goal is that it should be possible
to use some templates in Rust programs without the fear of pulling in complex
dependencies for a small problem. Additionally it tries not to re-invent
something but stay in line with prior art to leverage an already existing
ecosystem of editor integrations.
$ cargo tree
minimal v0.1.0 (examples/minimal)
└── minijinja v2.5.0 (minijinja)
└── serde v1.0.144
Additionally minijinja is also available as an (optionally pre-compiled) command line executable
called minijinja-cli:
$ curl -sSfL https://github.com/mitsuhiko/minijinja/releases/latest/download/minijinja-cli-installer.sh | sh
$ echo "Hello {{ name }}" | minijinja-cli - -Dname=World
Hello World
You can play with MiniJinja online in the browser playground powered by a WASM build of MiniJinja.
Goals:
- Well documented, compact API
- Minimal dependencies, reasonable compile times and decent runtime performance
- Stay as close as possible to Jinja2
- Support for expression evaluation which allows the use as a DSL
- Support for all
serdecompatible types - Well tested
- Support for dynamic runtime objects with methods and dynamic attributes
- Descriptive errors
- Compiles to WebAssembly
- Works with Python
- Comes with a handy CLI
- Experimental C-Bindings
Example Template:
{% extends "layout.html" %}
{% block body %}
<p>Hello {{ name }}!</p>
{% endblock %}Invoking from Rust:
use minijinja::{Environment, context};
fn main() {
let mut env = Environment::new();
env.add_template("hello.txt", "Hello {{ name }}!").unwrap();
let template = env.get_template("hello.txt").unwrap();
println!("{}", template.render(context! { name => "World" }).unwrap());
}Here are some interesting Open Source users and use cases of MiniJinja. The examples link directly to where the engine is used so you can see how it's utilized:
-
HTML Generation:
- Zine uses it to generate static HTML
- Oranda uses it to generate HTML landing pages
-
Structure Generation:
- Astral's Rye is using it to generate project structures
- Maturin uses it to generate project structures
- cargo-dist uses it to generate CI and project configuration
-
AI Chat Templating:
- HuggingFace uses it to render LLM chat templates
- mistral.rs uses it to render LLM chat templates
- BoundaryML's BAML uses it to render LLM chat templates
- LSP-AI uses it to render LLM chat templates
-
Data and Processing:
- Cube uses it for data modelling
- PRQL uses it to handle DBT style pipelines
- qsv uses it to render templates from CSV files and to construct payloads to post to web services.
If you are stuck with MiniJinja, have suggestions or need help, you can use the
GitHub Discussions.
- minijinja-autoreload: provides auto reloading functionality of environments
- minijinja-embed: provides utilities for embedding templates in a binary
- minijinja-contrib: provides additional utilities too specific for the core
- minijinja-py: makes MiniJinja available to Python
- minijinja-cli: a command line utility.
- minijinja-cabi: a C binding to MiniJinja.
These are related template engines for Rust:
- Askama: Jinja inspired, type-safe, requires template precompilation. Has significant divergence from Jinja syntax in parts.
- Rinja: Jinja inspired, type-safe, requires template precompilation. Has significant divergence from Jinja syntax in parts.
- Tera: Jinja inspired, dynamic, has divergences from Jinja.
- TinyTemplate: minimal footprint template engine with syntax that takes lose inspiration from Jinja and handlebars.
- Liquid: an implementation of Liquid templates for Rust. Liquid was inspired by Django from which Jinja took it's inspiration.
If you like the project and find it useful you can become a sponsor.
