mermaid-render

Mermaid 渲染

将 Mermaid 图表渲染为 SVG/PNG/PDF。支持标准 Mermaid 输出，也支持通过 svg2roughjs 实现的手绘（草图）风格——与 Mermaid Live Editor 的手绘模式效果相同。

默认启用手绘风格。使用 --no-handdrawn 可输出标准 Mermaid 图表。

何时使用此技能

1. 用户要求“渲染”“可视化”或“生成” Mermaid 图表
2. 用户提供了 .mmd 文件或 Mermaid 代码块，需要生成图像
3. 用户希望“创建流程图/时序图/状态图/类图/ER 图”
4. 用户需要从 Markdown 文档中提取并渲染图表
5. 用户希望“批量处理”一个 .mmd 文件目录
6. 用户提到“手绘”“草图”或“粗略”风格——保留默认设置或添加 --pencil-filter
7. 用户希望获得简洁的标准 Mermaid 输出（无手绘效果）——使用 --no-handdrawn

⚠️ 路径解析（重要）

所有脚本都位于与此 SKILL.md 相同的目录中。运行任何脚本前，必须确定此文件的实际路径，并据此得出脚本目录。

**规则：**将本文档中每个 $SKILL_DIR 占位符替换为包含此 SKILL.md 文件的目录的绝对路径。

例如：如果此文件位于 /path/to/mermaid-render/SKILL.md，那么 $SKILL_DIR = /path/to/mermaid-render。

SKILL_DIR="<absolute path to the directory containing this SKILL.md>"

---

快速开始

标准 Mermaid 输出（无手绘效果）

node "$SKILL_DIR/scripts/render.mjs" \
  --input diagram.mmd \
  --output diagram.svg \
  --no-handdrawn

手绘风格（默认）

node "$SKILL_DIR/scripts/render.mjs" \
  --input diagram.mmd \
  --output diagram.svg

输出为 PNG（高分辨率）

node "$SKILL_DIR/scripts/render.mjs" \
  --input diagram.mmd \
  --output diagram.png \
  --scale 2

输出为 PDF

node "$SKILL_DIR/scripts/render.mjs" \
  --input diagram.mmd \
  --output diagram.pdf \
  --pdf-fit

从 Markdown 中提取并渲染

node "$SKILL_DIR/scripts/render.mjs" \
  --input document.md \
  --output ./output-dir

批量渲染

node "$SKILL_DIR/scripts/batch.mjs" \
  --input-dir ./diagrams \
  --output-dir ./output

---

工作流

步骤 1：用户想要什么？

• 渲染现有 Mermaid 代码 → 保存为 .mmd 文件，使用 render.mjs
• 从 Markdown 中提取图表 → 直接传入 .md 文件
• 创建新图表 → 参考 $SKILL_DIR/assets/example_diagrams/ 中的模板
• 批量处理 → 使用 batch.mjs

步骤 2：选择输出风格

• 默认（手绘）——通过 svg2roughjs 实现草图/粗略风格，与 Mermaid Live Editor 相同
• --no-handdrawn ——简洁的标准 Mermaid 输出，无草图效果

步骤 3：选择输出格式

• svg ——矢量格式，适用于网页和文档（默认）
• png ——位图格式，适用于嵌入和分享（使用 --scale 调整分辨率）
• pdf ——适用于打印（使用 --pdf-fit 自动调整尺寸）

步骤 4：选择主题

• default ——Mermaid 默认主题
• neutral ——中性色调，适用于文档
• dark ——深色主题
• forest ——绿色主题

步骤 5：渲染

node "$SKILL_DIR/scripts/render.mjs" -i input.mmd -o output.svg --theme neutral

---

选项

render.mjs

选项	描述	默认值
-i, --input	输入文件（.mmd 或 .md）	必填
-o, --output	输出文件（.svg/.png/.pdf）	必填
-e, --format	输出格式：svg、png、pdf	根据扩展名推断
-t, --theme	Mermaid 主题	default
--bg	背景颜色	transparent
-w, --width	页面宽度	800
-H, --height	页面高度	600
-s, --scale	缩放比例（影响 PNG 分辨率）	1
-c, --config	Mermaid JSON 配置文件	无
-C, --css	自定义 CSS 文件	无
--pdf-fit	将 PDF 调整为图表大小	关闭
--icon-packs	图标包，以逗号分隔	无
--font	手绘模式的字体系列	Excalifont, Xiaolai, cursive
--pencil-filter	启用铅笔滤镜效果（仅限手绘）	关闭
--randomize	启用逐元素随机化（会导致排线密度变化）	关闭
--seed	随机种子	无
--roughness	粗糙度级别（仅限手绘）	rough.js 默认值
--bowing	弯曲程度（仅限手绘）	rough.js 默认值
--hachure-gap	排线间距（单位：px，数值越小越密集）	2
--fill-weight	排线宽度（单位：px）	1.5
--no-handdrawn	跳过手绘转换，输出原始 Mermaid SVG	关闭

batch.mjs

选项	描述	默认值
-i, --input-dir	输入目录	必填
-o, --output-dir	输出目录	必填
-e, --format	输出格式：svg、png、pdf	svg
-t, --theme	Mermaid 主题	default
--bg	背景颜色	transparent
-s, --scale	缩放系数（影响 PNG 分辨率）	1
--font	字体系列（手绘模式）	Excalifont, Xiaolai, cursive
--pencil-filter	启用铅笔滤镜效果	关闭
--randomize	启用逐元素随机化	关闭
--seed	随机种子	无
--roughness	粗糙度级别	rough.js 默认值
--bowing	弯曲度级别	rough.js 默认值
--hachure-gap	排线间距，单位为 px	2
--fill-weight	排线宽度，单位为 px	1.5
--no-handdrawn	跳过手绘转换	关闭
--concurrency	最大并行渲染数	3

---

示例

流程图 — 标准样式

node "$SKILL_DIR/scripts/render.mjs" \
  --input "$SKILL_DIR/assets/example_diagrams/flowchart.mmd" \
  --output flowchart.svg \
  --no-handdrawn

流程图 — 手绘样式

node "$SKILL_DIR/scripts/render.mjs" \
  --input "$SKILL_DIR/assets/example_diagrams/flowchart.mmd" \
  --output flowchart.svg

时序图（高分辨率 PNG，中性主题）

node "$SKILL_DIR/scripts/render.mjs" \
  --input "$SKILL_DIR/assets/example_diagrams/sequence.mmd" \
  --output sequence.png \
  --scale 2 --theme neutral

状态图（自动适配 PDF）

node "$SKILL_DIR/scripts/render.mjs" \
  --input "$SKILL_DIR/assets/example_diagrams/state.mmd" \
  --output state.pdf \
  --pdf-fit --theme dark

从 Markdown 中提取所有图表

# Single code block → single output file
node "$SKILL_DIR/scripts/render.mjs" -i doc.md -o diagram.svg

# Multiple code blocks → output to directory (auto-named doc-1.svg, doc-2.svg, ...)
node "$SKILL_DIR/scripts/render.mjs" -i doc.md -o ./output-dir

自定义 Mermaid 配置

# config.json: { "theme": "neutral", "flowchart": { "curve": "basis" } }
node "$SKILL_DIR/scripts/render.mjs" \
  --input diagram.mmd \
  --output diagram.svg \
  --config config.json

自定义 CSS

node "$SKILL_DIR/scripts/render.mjs" \
  --input diagram.mmd \
  --output diagram.svg \
  --css custom.css

图标包

node "$SKILL_DIR/scripts/render.mjs" \
  --input diagram.mmd \
  --output diagram.svg \
  --icon-packs @iconify-json/logos

可复现的手绘输出（固定种子）

node "$SKILL_DIR/scripts/render.mjs" \
  --input diagram.mmd \
  --output diagram.svg \
  --seed 42 --no-randomize

铅笔滤镜效果

node "$SKILL_DIR/scripts/render.mjs" \
  --input diagram.mmd \
  --output diagram.svg \
  --pencil-filter

---

根据用户需求创建图表

步骤 1：确定图表类型

• 流程／工作流 → graph TD 或 flowchart LR
• API／交互 → sequenceDiagram
• 状态／生命周期 → stateDiagram-v2
• 对象模型 → classDiagram
• 数据库 → erDiagram
• 时间线 → timeline
• 甘特图／项目 → gantt
• 思维导图 → mindmap

步骤 2：创建 .mmd 文件 参考 $SKILL_DIR/assets/example_diagrams/ 中的模板。

步骤 3：渲染并迭代

node "$SKILL_DIR/scripts/render.mjs" -i diagram.mmd -o preview.svg
# Edit diagram.mmd based on feedback, re-render

---

功能

Mermaid 渲染

• 支持所有 Mermaid 图表类型（流程图、时序图、状态图、类图、ER 图、时间线、甘特图、思维导图等）
• 输出 SVG／PNG／PDF
• 支持 Markdown 输入（自动提取 Mermaid 代码块）
• 自动优化中日韩（CJK）文本
• 自定义 Mermaid 配置和 CSS
• 支持图标包（Iconify）
• 自定义主题：default、neutral、dark、forest

手绘样式（默认启用，使用 --no-handdrawn 禁用）

• 与 Mermaid Live Editor 的手绘模式完全一致（由 svg2roughjs 提供支持）
• 保留自定义节点颜色（样式指令）
• 铅笔滤镜效果
• 粗糙度和弯曲度控制
• 通过种子参数生成可复现的输出

依赖项

• Node.js 18+
• puppeteer、svg2roughjs 和 @mermaid-js/mermaid-cli（均通过 npm install 安装）

故障排除

未找到 mmdc

❌ @mermaid-js/mermaid-cli not found

解决方法： npm install

puppeteer 安装失败

Puppeteer 需要下载 Chromium。请确保网络连接正常。手动安装：

cd "$SKILL_DIR" && npm install

Mermaid 语法错误

渲染前，请在 https://mermaid.live/ 验证语法。

---

文件结构

scripts/

• render.mjs — 单文件渲染器（SVG/PNG/PDF，支持 Markdown 输入）
• batch.mjs — 批量渲染器

assets/

• example_diagrams/flowchart.mmd — 流程图模板
• example_diagrams/sequence.mmd — 时序图模板
• example_diagrams/state.mmd — 状态图模板