Back to Details

diagram

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/diagram - Mermaid Diagram Utility

/diagram - Mermaid 图表工具

Skill Awareness: See 
skills/_registry.md
for all available skills.
  • Use with: 
    /dev-scout
    for architecture visualization
  • Use with: 
    /dev-specs
    for flow diagrams
  • Related: 
    /docs-graph
    for document relationships
Create, validate, and fix Mermaid diagrams in markdown files.
技能说明: 查看 
skills/_registry.md
获取所有可用技能。
  • 搭配使用: 与 
    /dev-scout
    配合进行架构可视化
  • 搭配使用: 与 
    /dev-specs
    配合生成流程图
  • 相关技能: 
    /docs-graph
    用于展示文档关联关系
在Markdown文件中创建、验证并修复Mermaid图表。

Prerequisites

前置条件

bash
npm install -g @mermaid-js/mermaid-cli
Verify: 
mmdc --version
bash
npm install -g @mermaid-js/mermaid-cli
验证：
mmdc --version

Usage

使用方法

/diagram validate path/to/file.md     # Validate diagrams in file
/diagram validate                      # Validate file from context
/diagram fix path/to/file.md          # Validate and auto-fix
/diagram validate path/to/file.md     # 验证文件中的图表
/diagram validate                      # 验证上下文提供的文件
/diagram fix path/to/file.md          # 验证并自动修复

Workflow

工作流程

Validate Mode

验证模式

  1. Read the markdown file
  2. Extract all mermaid code blocks
  3. For each diagram, run: 
    mmdc -i <temp-file> -o /tmp/mermaid-out.svg 2>&1
  4. Report results:
    • Valid: Confirm with checkmark
    • Invalid: Show error, location, and what's wrong
  1. 读取Markdown文件
  2. 提取所有Mermaid代码块
  3. 对每个图表执行：
    mmdc -i <temp-file> -o /tmp/mermaid-out.svg 2>&1
  4. 报告结果：
    • 有效：显示对勾确认
    • 无效：显示错误信息、位置及问题原因

Fix Mode

修复模式

  1. Validate first
  2. For invalid diagrams:
    • Identify the error type (see 
      references/common-errors.md
      )
    • Apply fix
    • Re-validate
  3. Repeat until all diagrams pass
  4. Update the file with fixes
  1. 先执行验证
  2. 针对无效图表：
    • 识别错误类型（参考 
      references/common-errors.md
      ）
    • 应用修复方案
    • 重新验证
  3. 重复操作直到所有图表验证通过
  4. 将修复后的内容更新到文件中

Supported Diagram Types

支持的图表类型

Core Diagrams

核心图表

TypeKeywordUse For
Flowchart
flowchart
Process flows, decisions
Sequence
sequenceDiagram
API flows, interactions
State
stateDiagram-v2
Status lifecycle
ER Diagram
erDiagram
Database schema
Class
classDiagram
Object structures
类型关键字适用场景
流程图
flowchart
流程流转、决策逻辑
时序图
sequenceDiagram
API流程、交互逻辑
状态图
stateDiagram-v2
状态生命周期
ER图
erDiagram
数据库 schema
类图
classDiagram
对象结构

Charts & Visualization

图表与可视化

TypeKeywordUse For
Pie
pie
Distribution
XY Chart
xychart-beta
Line/bar charts, trends
Quadrant
quadrantChart
Priority matrix, effort/impact
Sankey
sankey-beta
Flow visualization, funnels
类型关键字适用场景
饼图
pie
数据分布展示
XY图表
xychart-beta
折线/柱状图、趋势分析
四象限图
quadrantChart
优先级矩阵、投入/产出分析
桑基图
sankey-beta
流量可视化、漏斗分析

Architecture & Systems

架构与系统

TypeKeywordUse For
Architecture
architecture-beta
AWS/Cloud diagrams, CI/CD
Block
block-beta
System blocks, layouts
C4
C4Context
/ 
C4Container
Software architecture levels
Packet
packet-beta
Network protocols
类型关键字适用场景
架构图
architecture-beta
AWS/云架构图、CI/CD流程
块图
block-beta
系统模块、布局展示
C4图
C4Context
/ 
C4Container
软件架构层级
数据包图
packet-beta
网络协议展示

Planning & Documentation

规划与文档

TypeKeywordUse For
Gantt
gantt
Project timelines
Timeline
timeline
Milestones, phases
Journey
journey
User experience mapping
Mindmap
mindmap
Feature breakdown
Git Graph
gitGraph
Branch strategies
Requirement
requirementDiagram
Requirements tracking
Kanban
kanban
Task boards
See 
references/diagram-types.md
for complete syntax and examples.
类型关键字适用场景
甘特图
gantt
项目时间线
时间线
timeline
里程碑、阶段展示
用户旅程图
journey
用户体验映射
思维导图
mindmap
功能拆解
Git图
gitGraph
分支策略展示
需求图
requirementDiagram
需求追踪
看板图
kanban
任务看板
查看 
references/diagram-types.md
获取完整语法及示例。

Architecture Diagrams (AWS/Cloud)

架构图（AWS/云）

The 
architecture-beta
type is specifically designed for cloud infrastructure diagrams.
architecture-beta
类型专为云基础设施图表设计。

Basic Components

基础组件

mermaid
architecture-beta
    group aws(cloud)[AWS Region]

    group vpc(cloud)[VPC] in aws
    service alb(server)[Load Balancer] in vpc
    service ec2(server)[EC2] in vpc
    service rds(database)[RDS] in vpc
    service s3(disk)[S3] in aws

    alb:R --> L:ec2
    ec2:R --> L:rds
    ec2:B --> T:s3
mermaid
architecture-beta
    group aws(cloud)[AWS Region]

    group vpc(cloud)[VPC] in aws
    service alb(server)[Load Balancer] in vpc
    service ec2(server)[EC2] in vpc
    service rds(database)[RDS] in vpc
    service s3(disk)[S3] in aws

    alb:R --> L:ec2
    ec2:R --> L:rds
    ec2:B --> T:s3

Syntax Quick Reference

语法速查

ElementSyntax
Group
group id(icon)[Label]
Nested group
group id(icon)[Label] in parent
Service
service id(icon)[Label]
Service in group
service id(icon)[Label] in group
Edge
svc1:R --> L:svc2
Junction
junction id
元素语法
分组
group id(icon)[Label]
嵌套分组
group id(icon)[Label] in parent
服务
service id(icon)[Label]
分组内服务
service id(icon)[Label] in group
连线
svc1:R --> L:svc2
连接点
junction id

Default Icons

默认图标

cloud
, 
database
, 
disk
, 
internet
, 
server
cloud
, 
database
, 
disk
, 
internet
, 
server

Edge Directions

连线方向

L
(left), 
R
(right), 
T
(top), 
B
(bottom)
L
（左）, 
R
（右）, 
T
（上）, 
B
（下）

Custom AWS Icons

自定义AWS图标

For actual AWS icons, use Iconify integration:
service lambda(logos:aws-lambda)[Lambda]
service s3(logos:aws-s3)[S3]
Note: Custom icons require registering icon packs in the Mermaid config.
如需使用真实AWS图标，可集成Iconify：
service lambda(logos:aws-lambda)[Lambda]
service s3(logos:aws-s3)[S3]
注意：自定义图标需要在Mermaid配置中注册图标包。

Validation Script

验证脚本

bash
undefined
bash
undefined

Extract and validate mermaid blocks

提取并验证Mermaid代码块

Save mermaid content to temp file, then:

将Mermaid内容保存到临时文件，然后执行：

mmdc -i /tmp/mermaid-temp.mmd -o /tmp/mermaid-out.svg 2>&1
mmdc -i /tmp/mermaid-temp.mmd -o /tmp/mermaid-out.svg 2>&1

Exit code 0 = valid, non-zero = error

退出码0表示有效，非0表示错误

Stderr contains error details

标准错误输出包含错误详情

undefined
undefined

Error Handling

错误处理

When validation fails, the error message indicates:
  • Line number in the diagram
  • Error type (syntax, unknown keyword, etc.)
  • Suggestion for fix
Load 
references/common-errors.md
for fix patterns.
验证失败时，错误信息会包含：
  • 图表中的行号
  • 错误类型（语法错误、未知关键字等）
  • 修复建议
查看 
references/common-errors.md
获取错误模式及修复方案。

Integration

集成方式

Other skills can use diagram validation:
markdown
<!-- After creating mermaid diagram -->
1. Write the diagram to file
2. Run: mmdc -i <file> -o /tmp/validate.svg 2>&1
3. If error, fix and retry
4. Continue with skill workflow
其他技能可调用图表验证功能：
markdown
<!-- 创建Mermaid图表后 -->
1. 将图表写入文件
2. 执行：mmdc -i <file> -o /tmp/validate.svg 2>&1
3. 若出错，修复后重试
4. 继续执行技能工作流

Example

示例

User: /diagram validate plans/billing/brd/flows/FL-MAIN-001-overview.md

Claude: Validating mermaid diagrams in FL-MAIN-001-overview.md...

Found 2 diagrams:

1. Line 5-15: flowchart LR
   ✓ Valid

2. Line 20-35: sequenceDiagram
   ✗ Error: Parse error on line 8
   → "End" is a reserved word, wrap in quotes: "End"

Fixing diagram 2...
   Applied fix: End → "End"
   Re-validating... ✓ Valid

Updated file. All diagrams now valid.
用户: /diagram validate plans/billing/brd/flows/FL-MAIN-001-overview.md

Claude: 正在验证FL-MAIN-001-overview.md中的Mermaid图表...

找到2个图表：

1. 第5-15行：flowchart LR
   ✓ 验证通过

2. 第20-35行：sequenceDiagram
   ✗ 错误：第8行解析错误
   → "End"是保留字，请用引号包裹："End"

正在修复图表2...
   已应用修复：End → "End"
   重新验证... ✓ 验证通过

文件已更新。所有图表现在均验证通过。

References

参考资料

  • references/diagram-types.md
    - Syntax for each diagram type
  • references/common-errors.md
    - Error patterns and fixes
  • references/diagram-types.md
    - 各图表类型的语法说明
  • references/common-errors.md
    - 错误模式及修复方案