creating-mermaid-diagrams

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坐标。

Prerequisites

前置条件

Option A: Local (mmdc)

bash

npm install -g @mermaid-js/mermaid-cli
mmdc --version

Option B: Kroki API (no install)

bash

curl --version  # Just need curl

选项A：本地使用（mmdc）

bash

npm install -g @mermaid-js/mermaid-cli
mmdc --version

选项B：使用Kroki API（无需安装）

bash

curl --version  # 仅需curl工具

Workflow

工作流程

Update check (notify, don't pull) — first use per conversation. Throttle to once per 24 h via
```
<this-skill-dir>/.last_update
```
; never mutate the skill directory without explicit user consent.
- If
```
.last_update
```
  exists and is <24 h old, skip this step entirely.
- Otherwise, fetch the latest tag from upstream:
  bash
```
git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
  | awk '{print $2}' | sed 's|refs/tags/||' | sort -V | tail -1
```
- Compare with this skill's
```
metadata.version
```
  from the frontmatter. If the upstream tag is strictly newer (semver), tell the user one line and ask:
  "A newer version of this skill is available: vX.Y.Z → vA.B.C. Want me to
  git pull
  ?"
  If they say yes, run
```
git -C <this-skill-dir> pull --ff-only
```
  . Refresh
```
.last_update
```
  either way so the prompt doesn't repeat for 24 hours.
- If upstream is the same or older, refresh
```
.last_update
```
  silently and continue.
- On any failure (offline, not a git checkout — e.g. ClawHub-installed copy, read-only path, no permission), swallow the error silently and continue with the user's task. Do not mention the failure.
Check deps — try
```
mmdc --version
```
, fallback to Kroki if unavailable
Pick diagram type — choose from table below
Generate — write
```
.mmd
```
file to disk
Validate — run validation (REQUIRED before export)
Export — use
```
mmdc
```
or Kroki API to produce PNG/SVG/PDF
Report — tell user the output file paths

版本更新检查（仅通知，不自动拉取） —— 每次对话首次使用时执行。通过
```
<this-skill-dir>/.last_update
```
文件限制为24小时一次；未经用户明确同意，绝不修改技能目录。
- 若
```
.last_update
```
  文件存在且生成时间小于24小时，直接跳过此步骤。
- 否则，从上游获取最新版本标签：
  bash
```
git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
  | awk '{print $2}' | sed 's|refs/tags/||' | sort -V | tail -1
```
- 将其与技能前置元数据中的
```
metadata.version
```
  对比。若上游版本标签更新（遵循语义化版本规则），向用户发送一行提示并询问：
  "此Skill有新版本可用：vX.Y.Z → vA.B.C。是否需要执行
  git pull
  更新？"
  若用户同意，运行
```
git -C <this-skill-dir> pull --ff-only
```
  。无论用户是否同意，都刷新
```
.last_update
```
  文件，确保24小时内不再重复提示。
- 若上游版本与当前版本相同或更旧，静默刷新
```
.last_update
```
  文件并继续执行任务。
- 若遇到任何失败（离线、非Git检出版本——如ClawHub安装的副本、只读路径、无权限等），静默忽略错误并继续执行用户任务，不得提及失败情况。
依赖检查 —— 尝试执行
```
mmdc --version
```
，若不可用则 fallback 到Kroki
选择图表类型 —— 从下方表格中选择
生成图表 —— 将
```
.mmd
```
文件写入磁盘
验证（必填） —— 运行验证（导出前必须执行）
导出 —— 使用
```
mmdc
```
或Kroki API生成PNG/SVG/PDF文件
反馈结果 —— 告知用户输出文件路径

Validation (Required)

验证（必填）

NEVER export a diagram without validating first.

bash

undefined

绝对禁止未验证就导出图表。

bash

undefined

Validate with mmdc (local)

使用本地mmdc验证

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

Validate with Kroki (if mmdc unavailable)

若mmdc不可用，使用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"

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


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

Diagram Types

图表类型

Type	Keyword	Use 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 architecture
Mind Map	`mindmap`	topic breakdowns

类型	关键字	使用场景
流程图	`flowchart TD/LR`	流程、流水线、决策逻辑
时序图	`sequenceDiagram`	API调用、消息传递
类图	`classDiagram`	面向对象模型、数据结构
ER图	`erDiagram`	数据库模式
状态图	`stateDiagram-v2`	状态机、生命周期
甘特图	`gantt`	项目时间线
饼图	`pie`	比例展示
Git图谱	`gitGraph`	分支策略
C4上下文图	`C4Context`	高层架构
思维导图	`mindmap`	主题拆解

Syntax Reference

语法参考

Flowchart: See reference/FLOWCHART.md Sequence: See reference/SEQUENCE.md Class & ER: See reference/CLASS-ER.md Other types: See reference/OTHER-TYPES.md

流程图：查看 reference/FLOWCHART.md 时序图：查看 reference/SEQUENCE.md 类图与ER图：查看 reference/CLASS-ER.md 其他类型：查看 reference/OTHER-TYPES.md

Examples

示例

Example 1: API Authentication Flow

示例1：API认证流程

User prompt:

Create a sequence diagram for JWT authentication

Generated
.mmd
:

mermaid

sequenceDiagram
  participant C as Client
  participant G as API Gateway
  participant A as Auth Service
  participant D as Database

  C->>G: POST /login {email, password}
  G->>A: validate(credentials)
  A->>D: SELECT user WHERE email=?
  D-->>A: user record
  A-->>A: verify password hash
  A-->>G: 200 OK + JWT token
  G-->>C: {token: "eyJhbG..."}

Output files:

auth-flow.mmd

auth-flow.png

用户提示：

创建JWT认证的时序图

生成的
.mmd
文件：

mermaid

sequenceDiagram
  participant C as Client
  participant G as API Gateway
  participant A as Auth Service
  participant D as Database

  C->>G: POST /login {email, password}
  G->>A: validate(credentials)
  A->>D: SELECT user WHERE email=?
  D-->>A: user record
  A-->>A: verify password hash
  A-->>G: 200 OK + JWT token
  G-->>C: {token: "eyJhbG..."}

输出文件：

auth-flow.mmd

auth-flow.png

Example 2: Microservices Architecture

示例2：微服务架构

User prompt:

Draw an e-commerce microservices architecture

Generated
.mmd
:

mermaid

flowchart TD
  subgraph Clients
    M[Mobile App]
    W[Web App]
  end

  GW[API Gateway]

  subgraph Services
    US[User Service]
    OS[Order Service]
    PS[Product Service]
    PAY[Payment Service]
  end

  subgraph Data
    UDB[(User DB)]
    ODB[(Order DB)]
    PDB[(Product DB)]
    REDIS[(Redis Cache)]
  end

  M & W --> GW
  GW --> US & OS & PS & PAY
  US --> UDB
  OS --> ODB
  PS --> PDB
  PAY --> REDIS

Output files:

ecommerce-arch.mmd

ecommerce-arch.png

用户提示：

绘制电商微服务架构图

生成的
.mmd
文件：

mermaid

flowchart TD
  subgraph Clients
    M[Mobile App]
    W[Web App]
  end

  GW[API Gateway]

  subgraph Services
    US[User Service]
    OS[Order Service]
    PS[Product Service]
    PAY[Payment Service]
  end

  subgraph Data
    UDB[(User DB)]
    ODB[(Order DB)]
    PDB[(Product DB)]
    REDIS[(Redis Cache)]
  end

  M & W --> GW
  GW --> US & OS & PS & PAY
  US --> UDB
  OS --> ODB
  PS --> PDB
  PAY --> REDIS

输出文件：

ecommerce-arch.mmd

ecommerce-arch.png

Example 3: Order State Machine

示例3：订单状态机

User prompt:

Show order lifecycle states

Generated
.mmd
:

mermaid

stateDiagram-v2
  [*] --> Pending : order created
  Pending --> Confirmed : payment success
  Pending --> Cancelled : timeout/cancel
  Confirmed --> Shipped : dispatched
  Shipped --> Delivered : received
  Delivered --> [*]
  Cancelled --> [*]

Output files:

order-states.mmd

order-states.png

用户提示：

展示订单生命周期状态

生成的
.mmd
文件：

mermaid

stateDiagram-v2
  [*] --> Pending : order created
  Pending --> Confirmed : payment success
  Pending --> Cancelled : timeout/cancel
  Confirmed --> Shipped : dispatched
  Shipped --> Delivered : received
  Delivered --> [*]
  Cancelled --> [*]

输出文件：

order-states.mmd

order-states.png

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

PNG with theme (default | dark | neutral | forest | base)

指定主题的PNG格式（默认 | dark | neutral | forest | base）

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

SVG

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

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

PDF via Kroki

通过Kroki导出PDF

curl -X POST -H "Content-Type: text/plain" --data-binary @diagram.mmd https://kroki.io/mermaid/pdf -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

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


**Kroki优势：**
- 无需本地安装
- 在任何装有`curl`的系统上均可使用
- 支持20+图表类型（PlantUML、GraphViz、D2等）

**使用Kroki的场景：**
- `mmdc`安装失败
- 快速生成一次性图表
- 无Node.js环境的CI/CD流水线

Common Mistakes

常见错误

Mistake	Fix
`mmdc` not found	`npm install -g @mermaid-js/mermaid-cli`
Wrong arrow in sequence	Use `->>` for request, `-->>` for response
Special chars in label	Wrap in quotes: `A["Label: value"]`
Blank/small output	Add `-w 2048` flag
Participant order wrong	Declare `participant` explicitly at top
Subgraph name with spaces	Wrap in quotes: `subgraph "My Layer"`

错误	修复方案
找不到 `mmdc`	执行 `npm install -g @mermaid-js/mermaid-cli`
时序图箭头错误	请求使用 `->>` ，响应使用 `-->>`
标签包含特殊字符	用引号包裹： `A["Label: value"]`
输出空白/尺寸过小	添加 `-w 2048` 参数
参与者顺序错误	在顶部显式声明 `participant`
子图名称包含空格	用引号包裹： `subgraph "My Layer"`