mermaid-diagrams

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mermaid Diagrams

Mermaid 图表

Generate diagrams in markdown that render in GitHub, GitLab, VS Code, Obsidian, Notion.

生成可在GitHub、GitLab、VS Code、Obsidian、Notion中渲染的Markdown格式图表。

Quick Start

快速开始

markdown

```mermaid
flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
```

markdown

```mermaid
flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
```

Quick Decision Tree

快速决策树

What to visualize?
├─ Process, algorithm, decision flow    → flowchart
├─ API calls, service interactions      → sequenceDiagram
├─ Database tables, relationships       → erDiagram
├─ OOP, type hierarchy, domain model    → classDiagram
├─ State machine, lifecycle             → stateDiagram-v2
├─ System architecture, services        → flowchart + subgraphs (or C4Context)
├─ Project timeline, sprints            → gantt
├─ User experience, pain points         → journey
├─ Git branches                         → gitGraph
├─ Data distribution                    → pie
└─ Priority matrix                      → quadrantChart

要可视化什么？
├─ 流程、算法、决策流    → 流程图
├─ API调用、服务交互      → 时序图
├─ 数据库表、关系       → ER图
├─ 面向对象、类型层级、领域模型    → 类图
├─ 状态机、生命周期             → 状态机图
├─ 系统架构、服务        → 流程图+子图（或C4Context）
├─ 项目时间线、迭代            → 甘特图
├─ 用户体验、痛点         → 用户旅程图
├─ Git分支                         → Git分支图
├─ 数据分布                    → 饼图
└─ 优先级矩阵                      → 四象限图

Diagram Types

图表类型

Type	Declaration	Best For
Flowchart	`flowchart LR/TB`	Processes, decisions, data flow
Sequence	`sequenceDiagram`	API flows, service calls
ER	`erDiagram`	Database schemas
Class	`classDiagram`	Types, domain models
State	`stateDiagram-v2`	State machines
Gantt	`gantt`	Project timelines
Journey	`journey`	User experience
C4	`C4Context`	System architecture
Git	`gitGraph`	Branch visualization

类型	声明语法	最佳适用场景
流程图	`flowchart LR/TB`	流程、决策、数据流
时序图	`sequenceDiagram`	API流程、服务调用
ER图	`erDiagram`	数据库Schema
类图	`classDiagram`	类型、领域模型
状态机图	`stateDiagram-v2`	状态机
甘特图	`gantt`	项目时间线
用户旅程图	`journey`	用户体验
C4架构图	`C4Context`	系统架构
Git分支图	`gitGraph`	分支可视化

Common Patterns

常用示例

System Architecture

系统架构

mermaid

flowchart LR
    subgraph Client
        Browser & Mobile
    end
    subgraph Services
        API --> Auth & Core
    end
    subgraph Data
        DB[(PostgreSQL)]
    end
    Client --> API
    Core --> DB

mermaid

flowchart LR
    subgraph Client
        Browser & Mobile
    end
    subgraph Services
        API --> Auth & Core
    end
    subgraph Data
        DB[(PostgreSQL)]
    end
    Client --> API
    Core --> DB

API Request Flow

API请求流程

mermaid

sequenceDiagram
    autonumber
    Client->>+API: POST /orders
    API->>Auth: Validate
    Auth-->>API: OK
    API->>+DB: Insert
    DB-->>-API: ID
    API-->>-Client: 201 Created

mermaid

sequenceDiagram
    autonumber
    Client->>+API: POST /orders
    API->>Auth: Validate
    Auth-->>API: OK
    API->>+DB: Insert
    DB-->>-API: ID
    API-->>-Client: 201 Created

Database Schema

数据库Schema

mermaid

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    USER { uuid id PK; string email UK }
    ORDER { uuid id PK; uuid user_id FK }

mermaid

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    USER { uuid id PK; string email UK }
    ORDER { uuid id PK; uuid user_id FK }

State Machine

状态机

mermaid

stateDiagram-v2
    [*] --> Draft
    Draft --> Submitted : submit()
    Submitted --> Approved : approve()
    Submitted --> Rejected : reject()
    Approved --> [*]

mermaid

stateDiagram-v2
    [*] --> Draft
    Draft --> Submitted : submit()
    Submitted --> Approved : approve()
    Submitted --> Rejected : reject()
    Approved --> [*]

Syntax Quick Reference

语法速查

Flowchart Nodes

流程图节点

[Rectangle]  (Rounded)  {Diamond}  [(Database)]  [[Subroutine]]
((Circle))   >Asymmetric]   {{Hexagon}}

[矩形]  (圆角矩形)  {菱形}  [(数据库)]  [[子程序]]
((圆形))   >不对称形状]   {{六边形}}

Flowchart Edges

流程图连线

A --> B       # Arrow
A --- B       # Line
A -.-> B      # Dotted arrow
A ==> B       # Thick arrow
A -->|text| B # Labeled

A --> B       # 箭头
A --- B       # 直线
A -.-> B      # 虚线箭头
A ==> B       # 粗箭头
A -->|文本| B # 带标签

Sequence Arrows

时序图箭头

->>   # Solid arrow (request)
-->>  # Dotted arrow (response)
-x    # X end (async)
-)    # Open arrow

->>   # 实心箭头（请求）
-->>  # 虚线箭头（响应）
-x    # 带X结尾（异步）
-)    # 开放箭头

ER Cardinality

ER图基数

||--||   # One to one
||--o{   # One to many
}o--o{   # Many to many

||--||   # 一对一
||--o{   # 一对多
}o--o{   # 多对多

Best Practices

最佳实践

Choose the right type — Use decision tree above
Keep focused — One concept per diagram
Use meaningful labels — Not just A, B, C
Direction matters —
```
LR
```
for flows,
```
TB
```
for hierarchies
Group with subgraphs — Organize related nodes

选择合适的图表类型 — 参考上方的决策树
保持聚焦 — 每个图表对应一个核心概念
使用有意义的标签 — 不要只用A、B、C这类代号
注意方向 —
```
LR
```
适用于流程，
```
TB
```
适用于层级结构
用子图分组 — 组织相关节点

Reference Documentation

参考文档

File	Purpose
references/FLOWCHARTS.md	Nodes, edges, subgraphs, styling
references/SEQUENCE.md	Participants, messages, activation
references/CLASS-ER.md	Classes, ER diagrams, relationships
references/STATE-JOURNEY.md	States, user journeys
references/DATA-CHARTS.md	Gantt, Pie, Timeline, Quadrant
references/ARCHITECTURE.md	C4, Block, Kanban
references/CHEATSHEET.md	All syntax quick reference

文件	用途
references/FLOWCHARTS.md	节点、连线、子图、样式
references/SEQUENCE.md	参与者、消息、激活
references/CLASS-ER.md	类、ER图、关系
references/STATE-JOURNEY.md	状态、用户旅程
references/DATA-CHARTS.md	甘特图、饼图、时间线、四象限图
references/ARCHITECTURE.md	C4模型、块图、看板
references/CHEATSHEET.md	全语法速查

Resources

资源

Official Documentation: https://mermaid.js.org
Live Editor: https://mermaid.live
GitHub Repository: https://github.com/mermaid-js/mermaid
GitHub Markdown Support: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams
GitLab Markdown Support: https://docs.gitlab.com/ee/user/markdown.html#diagrams-and-flowcharts

官方文档: https://mermaid.js.org
在线编辑器: https://mermaid.live
GitHub仓库: https://github.com/mermaid-js/mermaid
GitHub Markdown支持: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams
GitLab Markdown支持: https://docs.gitlab.com/ee/user/markdown.html#diagrams-and-flowcharts