mermaid-diagrams

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mermaid Diagramming

Mermaid 绘图

Create professional software diagrams using Mermaid's text-based syntax. Mermaid renders diagrams from simple text definitions, making diagrams version-controllable, easy to update, and maintainable alongside code.

使用Mermaid的基于文本的语法创建专业的软件图表。Mermaid通过简单的文本定义渲染图表，使图表可版本控制、易于更新，并能与代码一起维护。

Core Syntax Structure

核心语法结构

All Mermaid diagrams follow this pattern:

mermaid

diagramType
  definition content

Key principles:

First line declares diagram type (e.g.,
```
classDiagram
```
,
```
sequenceDiagram
```
,
```
flowchart
```
)
Use
```
%%
```
for comments
Line breaks and indentation improve readability but aren't required
Unknown words break diagrams; parameters fail silently

所有Mermaid图表都遵循以下模式：

mermaid

diagramType
  definition content

关键原则：

第一行声明图表类型（例如：
```
classDiagram
```
、
```
sequenceDiagram
```
、
```
flowchart
```
）
使用
```
%%
```
添加注释
换行和缩进可提升可读性，但并非必需
未知词汇会导致图表出错；参数错误不会显示提示

Diagram Type Selection Guide

图表类型选择指南

Choose the right diagram type:

Class Diagrams - Domain modeling, OOP design, entity relationships
- Domain-driven design documentation
- Object-oriented class structures
- Entity relationships and dependencies
Sequence Diagrams - Temporal interactions, message flows
- API request/response flows
- User authentication flows
- System component interactions
- Method call sequences
Flowcharts - Processes, algorithms, decision trees
- User journeys and workflows
- Business processes
- Algorithm logic
- Deployment pipelines
Entity Relationship Diagrams (ERD) - Database schemas
- Table relationships
- Data modeling
- Schema design
C4 Diagrams - Software architecture at multiple levels
- System Context (systems and users)
- Container (applications, databases, services)
- Component (internal structure)
- Code (class/interface level)
State Diagrams - State machines, lifecycle states
Git Graphs - Version control branching strategies
Gantt Charts - Project timelines, scheduling
Pie/Bar Charts - Data visualization

选择合适的图表类型：

类图 - 领域建模、面向对象设计、实体关系
- 领域驱动设计文档
- 面向对象类结构
- 实体关系与依赖
序列图 - 时序交互、消息流
- API请求/响应流程
- 用户认证流程
- 系统组件交互
- 方法调用序列
流程图 - 流程、算法、决策树
- 用户旅程与工作流
- 业务流程
- 算法逻辑
- 部署流水线
实体关系图（ERD） - 数据库模式
- 表关系
- 数据建模
- 模式设计
C4图 - 多层面软件架构
- 系统上下文（系统与用户）
- 容器（应用、数据库、服务）
- 组件（内部结构）
- 代码（类/接口层面）
状态图 - 状态机、生命周期状态
Git图 - 版本控制分支策略
甘特图 - 项目时间线、调度
饼图/柱状图 - 数据可视化

Quick Start Examples

快速入门示例

Class Diagram (Domain Model)

类图（领域模型）

mermaid

classDiagram
    Title -- Genre
    Title *-- Season
    Title *-- Review
    User --> Review : creates

    class Title {
        +string name
        +int releaseYear
        +play()
    }

    class Genre {
        +string name
        +getTopTitles()
    }

mermaid

classDiagram
    Title -- Genre
    Title *-- Season
    Title *-- Review
    User --> Review : creates

    class Title {
        +string name
        +int releaseYear
        +play()
    }

    class Genre {
        +string name
        +getTopTitles()
    }

Sequence Diagram (API Flow)

序列图（API流程）

mermaid

sequenceDiagram
    participant User
    participant API
    participant Database

    User->>API: POST /login
    API->>Database: Query credentials
    Database-->>API: Return user data
    alt Valid credentials
        API-->>User: 200 OK + JWT token
    else Invalid credentials
        API-->>User: 401 Unauthorized
    end

mermaid

sequenceDiagram
    participant User
    participant API
    participant Database

    User->>API: POST /login
    API->>Database: Query credentials
    Database-->>API: Return user data
    alt Valid credentials
        API-->>User: 200 OK + JWT token
    else Invalid credentials
        API-->>User: 401 Unauthorized
    end

Flowchart (User Journey)

流程图（用户旅程）

mermaid

flowchart TD
    Start([User visits site]) --> Auth{Authenticated?}
    Auth -->|No| Login[Show login page]
    Auth -->|Yes| Dashboard[Show dashboard]
    Login --> Creds[Enter credentials]
    Creds --> Validate{Valid?}
    Validate -->|Yes| Dashboard
    Validate -->|No| Error[Show error]
    Error --> Login

mermaid

flowchart TD
    Start([User visits site]) --> Auth{Authenticated?}
    Auth -->|No| Login[Show login page]
    Auth -->|Yes| Dashboard[Show dashboard]
    Login --> Creds[Enter credentials]
    Creds --> Validate{Valid?}
    Validate -->|Yes| Dashboard
    Validate -->|No| Error[Show error]
    Error --> Login

ERD (Database Schema)

ERD（数据库模式）

mermaid

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : includes

    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }

    ORDER {
        int id PK
        int user_id FK
        decimal total
        datetime created_at
    }

mermaid

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : includes

    USER {
        int id PK
        string email UK
        string name
        datetime created_at
    }

    ORDER {
        int id PK
        int user_id FK
        decimal total
        datetime created_at
    }

Detailed References

详细参考文档

For in-depth guidance on specific diagram types, see:

references/class-diagrams.md - Domain modeling, relationships (association, composition, aggregation, inheritance), multiplicity, methods/properties
references/sequence-diagrams.md - Actors, participants, messages (sync/async), activations, loops, alt/opt/par blocks, notes
references/flowcharts.md - Node shapes, connections, decision logic, subgraphs, styling
references/erd-diagrams.md - Entities, relationships, cardinality, keys, attributes
references/c4-diagrams.md - System context, container, component diagrams, boundaries
references/architecture-diagrams.md - Cloud services, infrastructure, CI/CD deployments
references/advanced-features.md - Themes, styling, configuration, layout options

如需特定图表类型的深入指导，请查看：

references/class-diagrams.md - 领域建模、关系（关联、组合、聚合、继承）、多重性、方法/属性
references/sequence-diagrams.md - 参与者、消息（同步/异步）、激活、循环、alt/opt/par块、注释
references/flowcharts.md - 节点形状、连接、决策逻辑、子图、样式
references/erd-diagrams.md - 实体、关系、基数、键、属性
references/c4-diagrams.md - 系统上下文、容器、组件图、边界
references/architecture-diagrams.md - 云服务、基础设施、CI/CD部署
references/advanced-features.md - 主题、样式、配置、布局选项

Best Practices

最佳实践

Start Simple - Begin with core entities/components, add details incrementally
Use Meaningful Names - Clear labels make diagrams self-documenting
Comment Extensively - Use
```
%%
```
comments to explain complex relationships
Keep Focused - One diagram per concept; split large diagrams into multiple focused views
Version Control - Store
```
.mmd
```
files alongside code for easy updates
Add Context - Include titles and notes to explain diagram purpose
Iterate - Refine diagrams as understanding evolves

从简开始 - 先从核心实体/组件入手，逐步添加细节
使用有意义的名称 - 清晰的标签让图表具备自文档性
大量添加注释 - 使用
```
%%
```
注释解释复杂关系
保持聚焦 - 一个图表对应一个概念；将大型图表拆分为多个聚焦视图
版本控制 - 将
```
.mmd
```
文件与代码一起存储，便于更新
添加上下文 - 包含标题和注释说明图表用途
迭代优化 - 随着理解深入不断完善图表

Configuration and Theming

配置与主题

Configure diagrams using frontmatter:

mermaid

---
config:
  theme: base
  themeVariables:
    primaryColor: "#ff6b6b"
---
flowchart LR
    A --> B

Available themes: default, forest, dark, neutral, base

Layout options:

```
layout: dagre
```
(default) - Classic balanced layout
```
layout: elk
```
- Advanced layout for complex diagrams (requires integration)

Look options:

```
look: classic
```
- Traditional Mermaid style
```
look: handDrawn
```
- Sketch-like appearance

使用前置元数据配置图表：

mermaid

---
config:
  theme: base
  themeVariables:
    primaryColor: "#ff6b6b"
---
flowchart LR
    A --> B

可用主题： default、forest、dark、neutral、base

布局选项：

```
layout: dagre
```
（默认）- 经典平衡布局
```
layout: elk
```
- 适用于复杂图表的高级布局（需要集成支持）

外观选项：

```
look: classic
```
- 传统Mermaid样式
```
look: handDrawn
```
- 手绘风格外观

Exporting and Rendering

导出与渲染

Native support in:

GitHub/GitLab - Automatically renders in Markdown
VS Code - With Markdown Mermaid extension
Notion, Obsidian, Confluence - Built-in support

Export options:

Mermaid Live Editor - Online editor with PNG/SVG export

Mermaid CLI -

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

then

mmdc -i input.mmd -o output.png

Docker -

docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png

原生支持平台：

GitHub/GitLab - 在Markdown中自动渲染
VS Code - 配合Markdown Mermaid扩展
Notion、Obsidian、Confluence - 内置支持

导出选项：

Mermaid Live Editor - 在线编辑器，支持PNG/SVG导出

Mermaid CLI -

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

然后执行

mmdc -i input.mmd -o output.png

Docker -

docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png

Common Pitfalls

常见陷阱

Breaking characters - Avoid
```
{}
```
in comments, use proper escape sequences for special characters
Syntax errors - Misspellings break diagrams; validate syntax in Mermaid Live
Overcomplexity - Split complex diagrams into multiple focused views
Missing relationships - Document all important connections between entities

特殊字符问题 - 避免在注释中使用
```
{}
```
，对特殊字符使用正确的转义序列
语法错误 - 拼写错误会导致图表失效；在Mermaid Live中验证语法
过度复杂 - 将复杂图表拆分为多个聚焦视图
缺失关系 - 记录实体之间所有重要的连接

When to Create Diagrams

何时创建图表

Always diagram when:

Starting new projects or features
Documenting complex systems
Explaining architecture decisions
Designing database schemas
Planning refactoring efforts
Onboarding new team members

Use diagrams to:

Align stakeholders on technical decisions
Document domain models collaboratively
Visualize data flows and system interactions
Plan before coding
Create living documentation that evolves with code

在以下场景务必创建图表：

启动新项目或新功能时
文档化复杂系统时
解释架构决策时
设计数据库模式时
规划重构工作时
新团队成员入职时

使用图表来：

让利益相关者在技术决策上达成一致
协作文档化领域模型
可视化数据流与系统交互
编码前进行规划
创建随代码一起演进的活文档