如何用 mermaid-rs-renderer 批量渲染 Markdown 中的 Mermaid 图表：CLI 实战指南-育师

【免费下载链接】mermaid-rs-renderer

A fast native Rust Mermaid diagram renderer. No browser required. 500-1000x faster than mermaid-cli.

项目地址：https://gitcode.com/gh_mirrors/me/mermaid-rs-renderer

mermaid-rs-renderer 是一款纯 Rust 编写的原生 Mermaid 图表渲染器，配套的mmdr命令行工具可以在一条命令内，批量提取并渲染 Markdown 文件中所有 Mermaid 图表为 SVG/PNG。它完全绕开了浏览器，比 mermaid-cli 快 500–1000 倍，是文档流水线、CI 构建和批量出图的理想选择。本文是一份面向新手的 CLI 实战指南，带你从安装到批量出图，一步步跑通整个流程。

为什么批量渲染需要 mermaid-rs-renderer 🚀

传统方案 mermaid-cli 每渲染一张图都要启动一次无头 Chromium 浏览器，单图固定开销约 2 秒。一篇包含 20 张图的文档，光浏览器启动就要等 40 秒以上。

而 mermaid-rs-renderer 用原生 Rust 实现了完整的 Mermaid 解析、布局与 SVG 渲染管线，冷启动仅约 3 毫秒：

使用场景	mermaid-cli	mmdr（mermaid-rs-renderer）
CI 流水线渲染 50 张图	~2 分钟	< 1 秒
实时编辑器预览	明显卡顿	即时
批量文档生成	咖啡凉了	一眨眼

更关键的是，mmdr 原生支持Markdown 批量模式：输入一个.md文件，它会自动提取其中全部 Mermaid 代码块并逐个渲染，无需你手写提取脚本。

一分钟安装：获取 mmdr 命令 📦

推荐通过 crates.io 一键安装：

cargo install mermaid-rs-renderer

如果从源码构建，可以先克隆仓库：

git clone https://gitcode.com/gh_mirrors/me/mermaid-rs-renderer cd mermaid-rs-renderer && cargo install --path .

macOS/Linux 也可用 Homebrew，Windows 可用 Scoop，详见 README.md 的安装章节。

核心用法：一条命令批量渲染 Markdown 图表 ✂️

这是全文最重要的一条命令——直接把整个 Markdown 文件交给 mmdr：

mmdr -i README.md -o ./diagrams/ -e svg

执行效果：

自动扫描README.md中的每一个 Mermaid 代码块（支持 `bash mmdr -i docs/guide.md -o ./img/ -e png

单文件模式同样简单： ```bash mmdr -i diagram.mmd -o output.svg -e svg # 流程图文件 → SVG echo 'flowchart LR; A-->B-->C' | mmdr -e svg # 管道输入 → 标准输出

常用 CLI 参数速查表 ⚙️

以下参数定义见 src/cli.rs，覆盖日常 90% 的批量渲染需求：

参数	作用	批量场景建议
`-i, --input`	输入文件（`.mmd`或`.md`），`-`表示 stdin	传`.md`即触发批量模式
`-o, --output`	输出文件/目录	目录自动编号命名
`-e, --outputFormat`	`svg`（默认）或`png`	文档网站用 svg，汇报用 png
`-t, --theme`	内置主题：default/dark/forest/neutral/modern	与站点主题保持一致
`-c, --configFile`	Mermaid 风格 config.json	统一主题变量、字体
`-w`/`-H`	强制输出宽高（像素）	控制 PNG 栅格尺寸
`--preferredAspectRatio`	期望宽高比，如`16:9`	幻灯图文图统一比例
`--nodeSpacing`/`--rankSpacing`	节点/层级间距	微调布局松紧
`--timing`	各阶段耗时以 JSON 输出到 stderr	性能分析
`--size`	仅输出每张图尺寸 JSON 并退出	预占版面、批量预处理
`--fastText`	快速文本度量	追求极限速度

主题示例：

mmdr -i README.md -o ./out/ -e svg -t modern

脚本集成：为 CI/文档流水线做批量预处理 🔗

批量渲染最常出现在自动化流水线中。mmdr 提供了两个纯 JSON 输出参数，方便被上游脚本消费：

先探测尺寸：mmdr -i docs.md -o ./out/ --size输出每张图的序号与宽高 JSON，不实际渲染，可用于预排版。
渲染时收集耗时：追加--timing，stderr 会输出 parse/layout/render 各阶段微秒数，便于定位慢图。

一个典型的文档生成流程：

# 1. 探测所有图表尺寸 mmdr -i docs/guide.md -o ./img/ --size > sizes.json # 2. 批量渲染 PNG（dark 主题，16:9 期望比例） mmdr -i docs/guide.md -o ./img/ -e png -t dark --preferredAspectRatio 16:9 # 3. 在 Markdown 中引用 ./img/diagram-1.png、./img/diagram-2.png ...

配合--configFile传入一份 JSON（含themeVariables、preferredAspectRatio、flowchart间距等），可以让整批图表风格完全统一，配置示例见 README.md。

性能实测：快多少？ ⚡

官方基准测试显示，即使包含进程启动与文件 I/O，mmdr 在 23 种图表类型上全面碾压 mermaid-cli（含 Chromium 冷启动）：

图表类型	mmdr	mermaid-cli	提速
Flowchart	4.49 ms	1,971 ms	439x
Class	4.67 ms	1,907 ms	408x
State	3.97 ms	1,968 ms	496x
Sequence	2.71 ms	1,906 ms	704x
200 节点大流程图	47.00 ms	2,276 ms	48x

字体缓存预热后，小图可再快 3 倍以上，小图整体提速达到 500–900 倍，开启--fastText后超过 1600 倍。完整数据见 docs/benchmarks.md，测试用例可参考 benches/typical/flowchart.mmd。

也就是说，一篇 30 张图的文档，mermaid-cli 需要约 1 分钟，mmdr 通常不到 0.2 秒——批量渲染从"等咖啡"变成"瞬间完成"。

常见问题 FAQ 🙋

Q1：我的 Markdown 里混用了```mermaid和~~~mermaid？A：两种围栏（以及 Pandoc 的::: mermaid）都能识别，按出现顺序统一编号输出。

Q2：批量渲染后图片命名能否自定义？A：mmdr 默认按diagram-N顺序命名。若需与文档章节对应，可先用--size探测数量，或自行按序号重排。

Q3：输出 PNG 报错 "requires the 'png' feature"？A：你的构建未启用 PNG 特性，按提示以cargo build --features png重新构建即可。

Q4：渲染效果不满意？A：先用-t切换内置主题，再用--nodeSpacing/--rankSpacing/--preferredAspectRatio微调布局；复杂需求写一份 config.json 通过-c传入。

总结 ✅

mermaid-rs-renderer（mmdr）把 Mermaid 图表的批量渲染变成了真正的一条命令：mmdr -i 文档.md -o 输出目录/ -e svg。无浏览器、无 Node.js 依赖、单图毫秒级，配合--timing、--size、主题与间距参数，足以覆盖文档站、CI 流水线和批量出图的绝大多数场景。现在就可以打开终端，试试把它接入你的下一条文档流水线。