rust-mustache

mustache (crate mustache, repository rust-mustache) is a Rust implementation of the Mustache templating specification — a logic-free template language that strictly separates presentation from application logic. It compiles a template once into a reusable Template value and renders it against any type implementing serde::Serialize, or against Data values built manually with the MapBuilder/VecBuilder helpers, including lazy values produced by closures.

The library supports the core Mustache tag set: escaped and unescaped interpolation, sections and inverted sections for conditional and iterative rendering, partials for template composition, and comments. It originated alongside the Nickel.rs web framework and has since served as a general-purpose templating engine wherever Rust code needs to produce HTML, text, or config output from structured data.

What You Get

• A Template type compiled once from a string, char iterator, or file, then rendered many times against different data.
• Automatic serde integration via to_data/render, so any #[derive(Serialize)] struct can be rendered without manual conversion.
• MapBuilder/VecBuilder fluent builders for constructing Data values by hand, including closure-backed lazy fields via insert_fn.
• Full core Mustache syntax: escaped/unescaped tags, sections, inverted sections, partials, and comments.

Common Use Cases

• Rendering HTML pages in a static site generator from serde-serializable front-matter/content structs.
• Generating text reports or changelogs from a Rust CLI tool using a single compiled template.
• Producing server-rendered HTML responses in a lightweight Rust web service.

Under The Hood

Architecture The crate is organized as a linear compile-then-render pipeline: parser::Parser turns a char iterator into a Vec<Token> (text, tags, sections, partials), compiler::Compiler wraps the parser and resolves referenced partial files relative to a Context (template path + extension), and template::Template holds the compiled tokens plus a RenderContext that walks the token tree with a data stack (Vec<&Data>) to support nested-scope lookups during rendering. Public entry points (compile_str, compile_iter, compile_path in src/lib.rs) all funnel through Context::compile, keeping construction centralized; the Data enum (built via builder::MapBuilder/VecBuilder or via serde through encoder::Encoder) is the one shared representation both paths converge on before rendering, so the render path never depends on how the data was produced.

Tech Stack The crate targets Rust 2015/2018-era idioms (extern crate declarations, positional struct-init) and depends on serde (1.x) for its Serialize-based data encoding, and log (0.3.x) for internal diagnostics via a custom bug! macro. Dev-dependencies (serde_derive, serde_json, tempdir) are used only for the test suite and README doctest. There is no async runtime, no build-time codegen, and no external template compiler — it is a pure, dependency-light Rust library shipped via Cargo/crates.io with an optional unstable feature flag gating nightly-only doc-inclusion behavior.

Code Quality The repository has a real, non-trivial test suite (tests/template.rs at 631 lines, plus tests/builder.rs, tests/macros.rs, tests/test.rs, and a spec submodule for spec-conformance data) exercising rendering, builders, and macro-driven fixtures, run via cargo test. Errors are modeled as a typed, non-exhaustive Error enum (InvalidStr, NoFilename, IncompleteSection, plus wrapped Io/Parser/Encoder variants) with From conversions rather than swallowed or stringly-typed failures. rustfmt.toml and .travis.yml show consistent formatting and CI were part of the workflow, though the project has been effectively unmaintained since 2023 (last push November 2023) and several dependency versions are pinned to older majors.

What Makes It Unique Its distinguishing design choice is treating serde::Serialize as the primary data-binding mechanism rather than requiring a bespoke encodable trait or reflection — any existing serde struct renders directly — while still offering an explicit Data/MapBuilder API for callers who want to assemble view data without a Rust type. This dual path (derive-based structs or hand-built builders, including closures for computed/lazy fields) gives it more flexibility than templating crates that only support one binding style, at the cost of being a smaller, less actively maintained project than newer alternatives like Handlebars-rust or Tera.