​​Mermaid​​ 是一个基于 JavaScript 的图表生成工具，使用 Markdown 风格的语法创建动态、可交互的图表。其核心优势：

• ​​纯文本语法​​：代码即图表，便于版本控制和协作
• ​​跨平台支持​​：可在 Obsidian、VS Code、GitHub、Notion 等平台使用
• ​​丰富的图表类型​​：支持超过 15 种专业图表
• ​​实时预览​​：大多数编辑器支持所见即所得渲染
• ​​定制化强大​​：支持主题、颜色、交互等高级配置

---

2. 基础语法结构

通用代码框架

在任何支持 Mermaid 的编辑器中使用：

```mermaid
<图表类型声明>
   <图表内容>
```

关键语法规则

1. ​​图表类型声明必须为首行​​：graph TD, sequenceDiagram 等
2. ​​缩进敏感​​：所有节点/关系定义需对齐
3. ​​注释​​：使用 %% 开头
4. ​​样式控制​​：使用 style 关键字
5. ​​特殊字符转义​​：使用双引号包裹内容 "text"

---

3. 图表类型详解

3.1 流程图 (Flowchart)

基本结构

方向控制

• TD/TB：上下布局（默认）
• LR：左右布局
• RL：右左布局
• BT：下上布局

节点形状

连接线样式

graph LR
  A --> B     : 实线箭头
  A --- C     : 实线无箭头
  A -.-> D    : 虚线箭头
  A ==> E     : 粗箭头
  A -- 文本 --> F  : 带标签箭头
  A -->|文本| G   : 另一种标签
  A --o H     : 空心箭头
  A --x I     : 叉形箭头

3.2 时序图 (Sequence Diagram)

关键符号

• ->>：实线箭头
• -->>：虚线箭头
• -x：异步消息（末端X）
• ->+：激活目标
• -->-：取消激活

3.3 类图 (Class Diagram)

关系类型

• <|--：继承
• *--：组合
• o--：聚合
• -->：关联
• ..|>：实现接口

3.4 状态图 (State Diagram)

stateDiagram-v2
  [*] --> Idle
  Idle --> Processing: OnRequest
  Processing --> Idle: OnComplete
  Processing --> Error: OnFailure
  
  state Processing {
    [*] --> Loading
    Loading --> Processing: OnLoaded
    Processing --> Saving
    Saving --> Completed
  }
  
  Error --> [*]: OnReset

3.5 甘特图 (Gantt)

gantt
  title 项目计划
  dateFormat YYYY-MM-DD
  axisFormat %m/%d
  
  section 设计
  需求收集     ：a1, 2023-10-01, 7d
  原型设计     ：after a1, 5d
  
  section 开发
  前端开发     : 2023-10-15, 20d
  后端开发     : crit, 2023-10-10, 25d
  
  section 测试
  单元测试     : 2023-11-05, 10d
  集成测试     : 2023-11-16, 7d

3.6 饼图 (Pie)

3.7 用户旅程图 (User Journey)

3.8 Git分支图 (Git Graph)

3.9 思维导图 (Mindmap)

3.10 实体关系图 (ER Diagram)

erDiagram
  CUSTOMER ||--o{ ORDER : places
  ORDER ||--|{ LINE-ITEM : contains
  CUSTOMER }|..| DELIVERY-ADDRESS : uses

---

4. 高级技巧

样式定制

交互功能

graph LR
  A[[文档]] click A "https://example.com" _blank
  B{API} click B callback "工具提示"

主题切换

子图

注释系统

---

5. 常见问题解决

错误：图表不渲染

1. 确认编辑器安装了 Mermaid 支持
2. 检查首行有图表类型声明
3. 确认所有节点使用了有效符号

错误：节点布局混乱

1. 统一所有连接符号格式（--> vs -->|text|）
2. 添加空白节点占位：

graph LR
  A --> B
  B --> C
  B --> D
  D --> E
  C --> E
  linkStyle 3 stroke:#fff,stroke-width:0px

性能优化

对于大型图表：

%%{init: { 'logLevel': 'fatal', 'theme': 'default' } }%%
graph TB
  ...

6. 完整配置参考

Mermaid 配置对象

{
  "theme": "default|forest|dark|neutral",
  "fontFamily": "Arial, sans-serif",
  "logLevel": 0|1|2|3|4|5,
  "securityLevel": "loose|strict|antiscript",
  "startOnLoad": true|false,
  "arrowMarkerAbsolute": false,
  "state": {
    "font-size": 14,
    "fill": "lightyellow"
  },
  "er": {
    "padding": 20
  }
}

Obsidian 集成配置

在 Obsidian 设置中启用 Mermaid 后，可在代码块添加：

%%{init: { 'theme': 'dark' }}%%

版权所有

许可证：署名 4.0 国际 (CC-BY-4.0)