Back to Details

mermaid-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Mermaid Diagrams

Mermaid图表

Generate 
.mmd
text files and export to PNG/SVG/PDF using 
mmdc
(local) or Kroki API (no install).
Key advantage: Text-based syntax with fully automatic layout — no x/y coordinates needed.
使用本地
mmdc
或无需安装的Kroki API生成
.mmd
文本文件并导出为PNG/SVG/PDF格式。
核心优势： 基于文本的语法搭配全自动布局——无需设置x/y坐标。

When to use / when NOT to use

适用场景/不适用场景

Use this skill for: diagrams-as-code with automatic layout (flowchart, sequence, class, state, ER, gantt, mindmap, architecture) — text source that lives in git and embeds in Markdown.
Do NOT use it — route elsewhere — for:
  • Pixel-precise placement, custom layout, branded icons, or heavy styling → drawio.
  • A hand-drawn / sketchy aesthetic → excalidraw or tldraw.
  • A freeform whiteboard or freehand strokes → tldraw.
  • Strict, conventional UML notation → plantuml.
本技能适用于： 具备自动布局的代码化图表（流程图、时序图、类图、状态图、ER图、甘特图、思维导图、架构图）——文本源码可存入git并嵌入Markdown。
请勿使用本技能，应转用其他工具的场景：
  • 像素级精确布局、自定义排版、品牌图标或复杂样式 → drawio。
  • 手绘/草图风格 → excalidraw 或 tldraw。
  • 自由白板或手绘笔触 → tldraw。
  • 严格规范的UML符号 → plantuml。

Prerequisites

前提条件

Option A: Local (mmdc) — also needs a headless Chrome (mmdc renders via Puppeteer)
bash
npm install -g @mermaid-js/mermaid-cli
npx puppeteer browsers install chrome-headless-shell   # required — mmdc has no bundled browser
mmdc --version
mmdc --version
succeeds even with no Chrome installed, but every export then fails with 
Could not find Chrome
. Install the browser above (or set 
PUPPETEER_EXECUTABLE_PATH
to a system Chrome). If you can't, use Kroki (Option B) — it needs no browser.
CI / Docker: mmdc crashes with 
Running as root without --no-sandbox
in containers. Pass the bundled puppeteer config (see 
scripts/puppeteer-config.json
):
bash
mmdc -p scripts/puppeteer-config.json -i diagram.mmd -o diagram.png
Option B: Kroki API (no install)
bash
curl --version  # Just need curl
选项A：本地使用（mmdc） —— 还需要无头Chrome浏览器（mmdc通过Puppeteer渲染）
bash
npm install -g @mermaid-js/mermaid-cli
npx puppeteer browsers install chrome-headless-shell   # 必须安装——mmdc未捆绑浏览器
mmdc --version
即使未安装Chrome，
mmdc --version
也会执行成功，但后续所有导出操作都会因
Could not find Chrome
失败。请安装上述浏览器（或设置
PUPPETEER_EXECUTABLE_PATH
指向系统已有的Chrome）。若无法安装，可使用选项B的Kroki——无需浏览器。
CI/ Docker环境： 在容器中以root身份运行mmdc会因
Running as root without --no-sandbox
崩溃。请传入捆绑的puppeteer配置（见
scripts/puppeteer-config.json
）：
bash
mmdc -p scripts/puppeteer-config.json -i diagram.mmd -o diagram.png
选项B：Kroki API（无需安装）
bash
curl --version  # 仅需curl

Workflow

工作流程

  1. Check deps — validate via Kroki (needs only 
    curl
    ); check 
    mmdc --version
    and a headless Chrome only when local export (PNG quality / PDF) is wanted
  2. Pick diagram type — choose from table below
  3. Generate — write 
    .mmd
    file to disk
  4. Validate — Kroki-first (see Validation; REQUIRED before export)
  5. Export — use 
    mmdc
    or Kroki API to produce PNG/SVG/PDF
  6. Self-check (vision) — read the exported PNG and fix readability/layout defects that automatic layout can't prevent (clipped labels, cramped density, wrong orientation), then re-validate + re-export. Max 2 rounds; skip if no vision. See Self-Check (vision) below.
  7. Review loop — show the image to the user, apply the minimal 
    .mmd
    edit per request, re-export until approved (5-round safety valve). See Review Loop below.
  8. Report — tell user the output file paths
  1. 检查依赖 —— 通过Kroki验证（仅需
    curl
    ）；仅当需要本地导出（PNG质量/PDF格式）时，检查
    mmdc --version
    是否可用以及有无无头Chrome浏览器
  2. 选择图表类型 —— 从下方表格中选择
  3. 生成图表 —— 将
    .mmd
    文件写入磁盘
  4. 验证 —— 优先使用Kroki（见验证部分；导出前必须执行）
  5. 导出 —— 使用
    mmdc
    或Kroki API生成PNG/SVG/PDF
  6. 自我检查（视觉校验） —— 查看导出的PNG，修复自动布局无法避免的可读性/布局缺陷（标签裁剪、密度拥挤、方向错误），然后重新验证并导出。最多2轮检查；若无视觉能力则跳过。详见下方自我检查（视觉校验）
  7. 审核循环 —— 向用户展示图片，根据请求对
    .mmd
    做最小修改，重新导出直至用户认可（最多5轮，超过则触发安全机制）。详见下方审核循环
  8. 反馈结果 —— 告知用户输出文件路径

Validation (Required)

验证（必填步骤）

NEVER export a diagram without validating first.
Prefer Kroki for validation — it needs no browser and sidesteps the 
Could not find Chrome
trap entirely. Use 
mmdc
for validation only when offline.
bash
undefined
导出图表前必须先验证。
优先使用Kroki进行验证——无需浏览器，完全规避
Could not find Chrome
问题。仅当离线时才使用
mmdc
验证。
bash
undefined

Validate with Kroki (preferred — no browser needed)

使用Kroki验证（优先选择——无需浏览器）

curl -s -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o /tmp/test.svg && echo "Valid" || echo "Invalid"
curl -s -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o /tmp/test.svg && echo "Valid" || echo "Invalid"

Validate with mmdc (offline fallback — requires headless Chrome)

使用mmdc验证（离线备选——需要无头Chrome）

mmdc -i diagram.mmd -o /tmp/test.svg 2>&1
mmdc -i diagram.mmd -o /tmp/test.svg 2>&1

If error, fix the .mmd file and validate again

若报错，修复.mmd文件后重新验证

Only proceed to export after validation passes

仅在验证通过后才能进行导出


Common validation errors:

- Missing quotes around labels with special characters
- Wrong arrow syntax (use `->>` for sequence, `-->` for flowchart)
- Undeclared participants in sequence diagrams

> A `Could not find Chrome` (or puppeteer) error from `mmdc` is a **setup** problem, not a diagram error — the `.mmd` may be perfectly valid. Validate via Kroki instead of "fixing" correct syntax.

常见验证错误：

- 含特殊字符的标签未加引号
- 箭头语法错误（时序图用`->>`，流程图用`-->`）
- 时序图中未声明参与者

> `mmdc`返回的`Could not find Chrome`（或puppeteer）错误是**环境配置**问题，而非图表语法错误——`.mmd`可能完全合法。请改用Kroki验证，而非修改正确的语法。

Self-Check (vision)

自我检查（视觉校验）

Zero-cost pre-check: before spending a vision call, read the PNG dimensions (
sips -g pixelWidth -g pixelHeight diagram.png
on macOS, 
file diagram.png
elsewhere). An extreme aspect ratio (longer side > 8x the shorter) is a "wrong orientation" defect — fix it without vision.
Validation (above) only proves the syntax is legal — it says nothing about whether the rendered diagram is readable. After exporting, use the agent's vision capability to read the PNG and catch what automatic layout can't prevent. Mermaid positions everything itself, so the failures here are about content and readability, not overlaps:
CheckWhat to look forFix
Label truncationNode / edge text clipped or cut offShorten the label, or wrap it with 
<br/>
Cramped, unreadable densityToo many nodes crammed together; tangled linesFlip direction (
TD
↔
LR
), split into 
subgraph
s, or reduce nodes
Wrong orientation / aspectDiagram far too wide or too tall to readChange 
flowchart TD
↔
LR
(or set 
direction
in class/state)
Edge spaghettiMany edges crossing, hard to followReorder node declarations so connected nodes sit adjacent; group with 
subgraph
Wrong diagram typeType doesn't suit the content (e.g. flowchart for a timeline)Switch type (
gantt
, 
sequenceDiagram
, 
stateDiagram-v2
, …)
Low contrastText blends into the node fillAdjust 
classDef
/ theme so text contrasts the fill
  • Max 2 self-check rounds — if issues remain after 2 fixes, show the user anyway.
  • Re-validate (syntax) and re-export after every fix.
  • If vision is unavailable, skip self-check and show the PNG directly.
零成本预检查： 在调用视觉能力前，先查看PNG尺寸（macOS用
sips -g pixelWidth -g pixelHeight diagram.png
，其他系统用
file diagram.png
）。极端宽高比（长边大于短边8倍以上）属于“方向错误”缺陷——无需视觉能力即可修复。
上述验证仅能证明语法合法，但无法保证渲染后的图表可读。导出后，使用智能体的视觉能力查看PNG，捕捉自动布局无法避免的问题。Mermaid会自动定位所有元素，因此此处的问题均与内容和可读性有关，不涉及元素重叠：
检查项检查内容修复方法
标签截断节点/边的文本被裁剪或截断缩短标签，或使用
<br/>
换行
密度拥挤、可读性差节点过多过于密集；线条混乱翻转方向（
TD
↔
LR
）、拆分为
subgraph
、减少节点数量
方向/宽高比错误图表过宽或过高，难以阅读修改
flowchart TD
↔
LR
（或在类图/状态图中设置
direction
）
线条混乱大量线条交叉，难以追踪调整节点声明顺序，使关联节点相邻；用
subgraph
分组
图表类型错误类型不匹配内容（如用流程图展示时间线）切换类型（
gantt
、
sequenceDiagram
、
stateDiagram-v2
等）
对比度低文字与节点背景融合调整
classDef
/主题，使文字与背景形成对比
  • 最多2轮自我检查——若2次修复后仍有问题，直接向用户展示即可。
  • 每次修复后都要重新验证（语法）并重新导出。
  • 若无视觉能力，跳过自我检查，直接展示PNG。

Review Loop

审核循环

After self-check, show the exported image and collect feedback. Apply the minimal 
.mmd
edit for each request, then re-validate and re-export:
User requestEdit action
Change a labelEdit the node / edge text in the 
.mmd
Add / remove a node or edgeAdd or delete the matching line
Change a colorAdd / adjust a 
classDef
and 
class <node> <className>
Change layout directionSwap 
TD
↔
LR
(flowchart) or set 
direction
(class / state)
Restructure / groupWrap related nodes in a 
subgraph
, or regenerate
  • Overwrite the same 
    diagram.mmd
    / 
    diagram.png
    each round — don't create 
    v1
    , 
    v2
    , …
  • Safety valve: after 5 rounds, generate a mermaid.live handoff link (see next section) so the user fine-tunes the current diagram in the browser.
自我检查完成后，向用户展示导出的图片并收集反馈。针对每个请求对
.mmd
做最小修改，然后重新验证并导出：
用户请求修改操作
修改标签编辑
.mmd
中的节点/边文本
添加/删除节点或边添加或删除对应的行
修改颜色添加/调整
classDef
并设置
class <node> <className>
修改布局方向切换
TD
↔
LR
（流程图）或设置
direction
（类图/状态图）
重构/分组将相关节点包裹在
subgraph
中，或重新生成
  • 每次修改都覆盖原有的
    diagram.mmd
    /
    diagram.png
    ——不要创建
    v1
    、
    v2
    等版本。
  • 安全机制： 超过5轮后，生成mermaid.live跳转链接（见下一节），让用户在浏览器中自行微调当前图表。

Mermaid.live Handoff

Mermaid.live 移交

When the review loop ends (approved or safety-valve), generate a one-click link that opens the current 
.mmd
in the mermaid.live editor for interactive fine-tuning:
bash
python3 scripts/mermaid_live_link.py diagram.mmd
当审核循环结束（用户认可或触发安全机制），生成一键链接，将当前
.mmd
打开在mermaid.live编辑器中进行交互式微调：
bash
python3 scripts/mermaid_live_link.py diagram.mmd

-> https://mermaid.live/edit#pako:...

-> https://mermaid.live/edit#pako:...


Pure `zlib` + `base64` (raw-deflate + URL-safe base64, same encoding mermaid.live uses), works offline. The script self-verifies with a round-trip decode before printing.

采用纯`zlib`+`base64`编码（原始压缩+URL安全base64，与mermaid.live使用的编码一致），离线可用。脚本会先进行往返解码验证，再输出链接。

Batch Mode (Repo Survey)

批量模式（仓库调研）

When the user asks to diagram a whole repo ("survey this codebase", "map the architecture"):
  1. Scan — locate schemas (SQL / ORM models), API routes, and state machines / lifecycle enums in the codebase
  2. Propose — one diagram per finding: ER for the schema, sequence for a main API flow, state for a lifecycle, flowchart for overall service layout; confirm the set with the user before generating
  3. Generate + export — run the standard workflow per diagram into one output folder
  4. Overview page — inline every exported SVG into a single self-contained 
    index.html
    (title + one section per diagram, no CDN), so the user opens one file
Same validation and self-check rules apply to every diagram in the batch.
当用户要求为整个仓库生成图表（如“调研此代码库”、“绘制架构图”）：
  1. 扫描 —— 在代码库中定位模式文件（SQL/ORM模型）、API路由、状态机/生命周期枚举
  2. 提议 —— 为每个发现生成一个图表：模式用ER图，主API流用时序图，生命周期用状态图，整体服务布局用流程图；生成前先与用户确认图表集合
  3. 生成+导出 —— 对每个图表执行标准工作流程，输出到同一个文件夹
  4. 概览页面 —— 将所有导出的SVG嵌入到单个自包含的
    index.html
    中（含标题和每个图表的章节，无需CDN），用户只需打开一个文件即可查看
批量模式下的每个图表都需遵循相同的验证和自我检查规则。

Diagram Types

图表类型

TypeKeywordUse for
Flowchart
flowchart TD/LR
processes, pipelines, decisions
Sequence
sequenceDiagram
API calls, message passing
Class
classDiagram
OOP models, data structures
ER
erDiagram
database schemas
State
stateDiagram-v2
state machines, lifecycle
Gantt
gantt
project timelines
Pie
pie
proportions
Git Graph
gitGraph
branch strategies
C4 Context
C4Context
high-level system context
Architecture
architecture-beta
cloud / CI/CD service layouts
Mind Map
mindmap
topic breakdowns
User Journey
journey
user-experience flows
Use Case
usecase-beta
actor–system interactions (UML)
Cynefin
cynefin-beta
sense-making / complexity domains
Event Modeling
eventmodeling
event-driven system timelines
Tree View
treeView-beta
file / directory hierarchies
Wardley Maps
wardley-beta
business strategy / value chains
类型关键字适用场景
流程图
flowchart TD/LR
流程、管道、决策逻辑
时序图
sequenceDiagram
API调用、消息传递
类图
classDiagram
OOP模型、数据结构
ER图
erDiagram
数据库模式
状态图
stateDiagram-v2
状态机、生命周期
甘特图
gantt
项目时间线
饼图
pie
比例展示
Git图
gitGraph
分支策略
C4上下文图
C4Context
高层系统上下文
架构图
architecture-beta
云/CI/CD服务布局
思维导图
mindmap
主题拆解
用户旅程图
journey
用户体验流程
用例图
usecase-beta
参与者-系统交互（UML）
Cynefin图
cynefin-beta
情境感知/复杂度领域
事件建模图
eventmodeling
事件驱动系统时间线
树视图
treeView-beta
文件/目录层级
Wardley图
wardley-beta
业务策略/价值链

Syntax Reference

语法参考

Flowchart: See reference/FLOWCHART.md Sequence: See reference/SEQUENCE.md Class & ER: See reference/CLASS-ER.md Architecture: See reference/ARCHITECTURE.md Use Case: See reference/USECASE.md Other types: See reference/OTHER-TYPES.md Themes & styling: See reference/THEMES.md
流程图：详见reference/FLOWCHART.md 时序图：详见reference/SEQUENCE.md 类图与ER图：详见reference/CLASS-ER.md 架构图：详见reference/ARCHITECTURE.md 用例图：详见reference/USECASE.md 其他类型：详见reference/OTHER-TYPES.md 主题与样式：详见reference/THEMES.md

Examples

示例

See reference/EXAMPLES.md for four worked examples (JWT auth sequence, microservices architecture, order state machine, cloud architecture) — each with the user prompt, the generated 
.mmd
, and the output files.
详见reference/EXAMPLES.md中的4个完整示例（JWT认证时序图、微服务架构图、订单状态机、云架构图）——每个示例都包含用户提示、生成的
.mmd
文件和输出文件。

Export Commands

导出命令

Option 1: Local Export (mmdc)

选项1：本地导出（mmdc）

Requires 
mmdc
installed locally. Best for offline use.
bash
undefined
需要本地安装
mmdc
。适合离线使用。
bash
undefined

PNG (recommended: 2048px wide, white background)

PNG（推荐：宽2048px，白色背景）

mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white
mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white

PNG with theme — valid -t values: default | dark | neutral | forest

带主题的PNG —— 有效的-t值：default | dark | neutral | forest

(
base
is NOT a valid -t value; it only works inside a %%{init: {'theme':'base'}}%% directive)

—
mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white --theme neutral
#（
base
不是有效的-t值；仅在%%{init: {'theme':'base'}}%%指令中生效） mmdc -i diagram.mmd -o diagram.png -w 2048 --backgroundColor white --theme neutral

SVG

SVG

mmdc -i diagram.mmd -o diagram.svg
mmdc -i diagram.mmd -o diagram.svg

PDF

PDF

mmdc -i diagram.mmd -o diagram.pdf
undefined
mmdc -i diagram.mmd -o diagram.pdf
undefined

Option 2: Kroki API (No Install Required)

选项2：Kroki API（无需安装）

Use Kroki when 
mmdc
is not available. No local dependencies needed.
bash
undefined
当
mmdc
不可用时使用Kroki。无需本地依赖。
bash
undefined

SVG via Kroki

通过Kroki导出SVG

curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o diagram.svg
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/svg -o diagram.svg

PNG via Kroki

通过Kroki导出PNG

curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/png -o diagram.png
curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/png -o diagram.png

PDF is NOT supported by Kroki for Mermaid — POSTing to /mermaid/pdf returns

Kroki不支持Mermaid导出PDF——向/mermaid/pdf发送POST请求会返回

HTTP 400 ("Unsupported output format: pdf for mermaid. Must be one of png or svg").

HTTP 400错误（"Unsupported output format: pdf for mermaid. Must be one of png or svg"）。

For PDF, use the local mmdc path instead: mmdc -i diagram.mmd -o diagram.pdf

如需PDF，请使用本地mmdc：mmdc -i diagram.mmd -o diagram.pdf


**Kroki advantages:**

- No local installation required
- Works on any system with `curl`
- Supports 20+ diagram types (PlantUML, GraphViz, D2, etc.)

**When to use Kroki:**

- `mmdc` installation fails
- Quick one-off diagrams
- CI/CD pipelines without Node.js

**Kroki优势：**

- 无需本地安装
- 任何有`curl`的系统都可使用
- 支持20+种图表类型（PlantUML、GraphViz、D2等）

**Kroki适用场景：**

- `mmdc`安装失败
- 快速生成一次性图表
- 无Node.js的CI/CD流水线

Common Mistakes

常见问题

MistakeFix
mmdc
not found
npm install -g @mermaid-js/mermaid-cli
mmdc
error 
Could not find Chrome
Install the headless browser: 
npx puppeteer browsers install chrome-headless-shell
(or use Kroki)
Kroki PDF fails with HTTP 400Kroki does PNG/SVG only for Mermaid; use local 
mmdc
for PDF
Valid diagram reported "invalid" by 
mmdc
The error is a Chrome/puppeteer setup failure, not a syntax error — don't rewrite correct 
.mmd
; fix the browser or validate via Kroki
Wrong arrow in sequenceUse 
->>
for request, 
-->>
for response
Special chars in labelWrap in quotes: 
A["Label: value"]
Blank/small outputAdd 
-w 2048
flag
Participant order wrongDeclare 
participant
explicitly at top
Subgraph name with spacesWrap in quotes: 
subgraph "My Layer"
问题解决方法
找不到
mmdc
命令		执行
npm install -g @mermaid-js/mermaid-cli
mmdc
报错
Could not find Chrome
安装无头浏览器：
npx puppeteer browsers install chrome-headless-shell
（或使用Kroki）
Kroki导出PDF返回HTTP 400错误Kroki仅支持Mermaid导出PNG/SVG；如需PDF请使用本地
mmdc
合法图表被
mmdc
报“无效”		该错误是Chrome/puppeteer配置问题，而非语法错误——不要修改正确的
.mmd
；修复浏览器或改用Kroki验证
时序图箭头错误请求用
->>
，响应用
-->>
标签含特殊字符用引号包裹：
A["Label: value"]
输出空白/尺寸过小添加
-w 2048
参数
参与者顺序错误在顶部显式声明
participant
子图名称含空格用引号包裹：
subgraph "My Layer"