liquid

liquid is a Rust implementation of the Liquid template language created by Shopify. It lets you render templates with a safe, sandboxed syntax — variables, filters, tags, and control flow — making it well suited for user-authored templates in static site generators, CMSs, and email/document rendering.

The project’s goals are conformance with strict shopify/liquid (incompatibilities are treated as bugs), flexibility to support domain-specific variants, and performance. It powers the Cobalt static site generator and ships as a workspace of crates (core, derive, lib) with an extensible filter and tag system.

What You Get

• A parser and renderer for the Liquid template language with Shopify conformance as a goal.
• A builder API (ParserBuilder) for configuring and compiling templates.
• An extensible system for custom filters, tags, and blocks.
• Partial-template support and a runtime object/value model with derive macros.
• A workspace of composable crates (liquid-core, liquid-derive, liquid-lib) plus a CLI helper crate.

Common Use Cases

• Rendering pages in a static site generator such as Cobalt.
• Letting end users author safe, sandboxed templates without exposing host internals.
• Generating emails, documents, or configuration from data-driven templates.
• Extending the template language with project-specific filters and tags.

Under The Hood

Architecture — The primary liquid crate (src/lib.rs, parser.rs, template.rs, partials.rs, reflection.rs) provides the high-level parse-and-render API, delegating to a Cargo workspace of member crates under crates/: core (value model, runtime, expression evaluation), lib (the standard filters/tags/blocks), derive (procedural macros for object reflection), plus bin and help-md helpers. Templates compile through a ParserBuilder into a reusable Template that renders against an object of runtime values.

Tech Stack — Rust 2021 with an MSRV of 1.83, organized as a resolver-2 workspace. It is dual-licensed MIT OR Apache-2.0 and uses cargo-deny, typos, and committed for supply-chain and quality gates. The design mirrors Shopify’s Ruby Liquid semantics.

Code Quality — Test coverage is deep and conformance-driven: tests/ contains dozens of files including a conformance_ruby/ suite that ports Ruby Liquid’s tests (the standard-filter test alone has ~78 cases), plus derive-macro, filter, syntax, error, and multithreading tests. Workspace-wide lints (unreachable_pub, unused_qualifications, rust_2018_idioms) are enforced, and the project has a long, actively maintained history led by epage.

API Design — The public API is ergonomic and well-documented: build a parser, parse a template string, and render with a value object. Extending the language with custom filters and tags follows clear trait-based patterns. Familiarity with Shopify Liquid transfers directly, and the derive macros reduce boilerplate when exposing Rust structs to templates, keeping the learning curve moderate.