mold 是一个面向 MoonBit 生态的轻量模板引擎。
mold is a lightweight template engine for the MoonBit ecosystem.
mold 当前聚焦在一个明确范围内：把模板稳定解析成 AST，再基于统一的 Value 模型完成渲染。它优先服务于报告生成、邮件模板、配置文件生成、文档模板这类文本生成场景，同时也支持通过显式配置进入 HTML 输出场景。
mold currently focuses on a clear scope: parse templates into ASTs and render them against a unified Value model. It primarily targets text generation scenarios such as reports, email templates, config files, and document generation, while also supporting HTML output through explicit configuration.
第一次接触 mold 时，建议按下面顺序阅读：
- 先看本页，了解项目定位、安装方式和三种推荐使用路径。
- 再看
docs/getting-started.md，把最小示例和运行方式跑通。 - 需要写模板时，看
docs/template-syntax.md。 - 需要多模板组合、HTML 输出或错误排查时，看对应进阶文档和 examples。
When reading mold for the first time, start with this page for project scope, installation, and the three recommended workflows, then move to getting-started, and finally to template-syntax when you begin writing templates.
moon add robinfang/mold
let output = @mold.render(
"Hello, {{ name }}!",
@mold.object({ "name": @mold.string("World") }),
)这三条路径对应 mold 的总体框架：
- 顶层函数：更轻，适合快速渲染
Template：更稳，适合 parse once, render manyEngine：更可扩展，适合 include、autoescape、自定义 filter
These three workflows map directly to the overall structure of mold: top-level rendering for quick use, Template for repeated rendering, and Engine for extensibility.
-
小模板或一次性渲染：
@mold.render(...) -
重复渲染同一模板：
Template::parse(...).render(...) -
需要 include、autoescape 或自定义 filter：
Engine -
Use
@mold.render(...)for small templates or one-off rendering. -
Use
Template::parse(...).render(...)when the same template is rendered repeatedly. -
Use
Enginewhen you need include, autoescape, or custom filters.
- 文档首页 / Docs index:
docs/index.md - 快速开始 / Getting started:
docs/getting-started.md - 模板语法 / Template syntax:
docs/template-syntax.md - Engine 指南 / Engine guide:
docs/engine-guide.md - HTML 安全 / HTML safety:
docs/html-safety.md - 错误排查 / Errors:
docs/errors.md - WASM 导出 / WASM export:
docs/wasm-export.md - Recipes / Recipes:
src/examples/hello/- 最小变量插值与 filter
- Minimal interpolation and filters
src/examples/report/- 循环、条件分支与嵌套对象
- Loops, conditionals, and nested objects
src/examples/email/- 更接近真实业务的文本模板
- A more realistic text template
src/examples/include_loader/Engine + Loader + include的模板组合- Template composition with
Engine + Loader + include
src/examples/html_safe/with_autoescape(true)与| safewith_autoescape(true)and| safe
src/examples/custom_filter/Engine::register_filter(...)自定义 filter- Custom filters via
Engine::register_filter(...)
src/examples/from_json/from_json(...)把 JSON 转成模板上下文- Convert JSON into template context with
from_json(...)
src/examples/site/- 静态网站批量渲染
- Static site batch rendering
运行示例 / Run an example:
moon run src/examples/hello
moon run src/examples/include_loader
moon run src/examples/html_safe
moon run src/examples/custom_filter
moon run src/examples/from_json
- 纯文本渲染 / plain text rendering
{{ expr }}插值与点路径访问 / interpolation with dotted lookup{% if %}/{% else %}/{% endif %}条件分支 / conditional blocks{% for %}/{% endfor %}循环，支持嵌套控制块 / loops with nested control blocks- 内置 filters / built-in filters:
upperlowertrimdefault(...)join(...)escapelengthsafe
- 比较与布尔表达式 / comparison and boolean expressions:
== != < <= > >=and or not- parentheses grouping
{% include "template_name" %}模板包含 / template inclusion- whitespace control / 空白控制：
{%-/-%}和{{-/-}} {# ... #}模板注释 / template comments- Engine 级 autoescape / engine-level autoescape
Template::ast()调试访问 / AST debug accessorfrom_json/from_map上下文转换 / context conversion helpers- 结构化错误类型与源码位置 / structured errors with source spans
默认情况下，mold 不自动转义 HTML，适合通用文本生成场景。输出 HTML 时，建议显式使用 Engine::with_autoescape(true)。
By default, mold does not autoescape HTML, which keeps it suitable for general text generation. For HTML output, explicitly enable Engine::with_autoescape(true).
let engine = @mold.Engine::new().with_autoescape(true)
let output = engine.render(
"{{ user_input }} | {{ trusted_html | safe }}",
@mold.object({
"user_input": @mold.string("<strong>escaped</strong>"),
"trusted_html": @mold.string("<em>kept</em>"),
}),
)pub fn render(source : String, ctx : Value) -> String raise MoldError
pub fn Template::parse(source : String) -> Template raise MoldError
pub fn Template::render(self : Template, ctx : Value) -> String raise MoldError
pub fn Template::source(self : Template) -> String
pub fn Template::ast(self : Template) -> Array[Node]
pub fn Engine::new() -> Engine
pub fn Engine::with_loader(self : Engine, loader : Loader) -> Engine
pub fn Engine::with_autoescape(self : Engine, autoescape : Bool) -> Engine
pub fn Engine::register_filter(self : Engine, name : String, filter : Filter) -> Unit raise MoldError
pub fn Engine::parse(self : Engine, source : String) -> Template raise MoldError
pub fn Engine::render(self : Engine, source : String, ctx : Value) -> String raise MoldError- 不支持模板继承 / no template inheritance
- 不支持宏系统 / no macro system
- 不支持异步模板 / no async templates
- 不支持自动模板目录扫描 / no automatic template discovery
MoldLive 是一个在线模板游乐场，mold 编译为 WASM 在浏览器中直接运行：
- 三栏编辑器（模板 / JSON 数据 / 实时输出）
- 4 个内置示例（Hello / Email / SVG Card / Offline Report）
- mold 语法高亮
- 零后端，模板不离开你的浏览器
MoldLive is an online playground where mold runs as WASM directly in your browser:
- Three-panel editor (template / JSON data / live output)
- 4 built-in examples
- mold syntax highlighting
- Zero backend — templates never leave your browser
mold 已发布到 mooncakes.io，当前版本为 0.2.0。
mold is now published on mooncakes.io, and the current version is 0.2.0.
Apache-2.0