mdbook-mermaid 操作手册
mdbook-mermaid 用于在 mdBook 中渲染 Mermaid 图。最适合流程图、时序图、状态图、ER 图以及各种关系图。
原仓库：https://github.com/badboy/mdbook-mermaid
流程图
样例：横向流程
flowchart LR
A[输入] --> B{检查}
B -->|通过| C[处理]
B -->|失败| D[报错]
对应源码：
```mermaid
flowchart LR
A[输入] --> B{检查}
B -->|通过| C[处理]
B -->|失败| D[报错]
```
方向可用：
LR：从左到右
RL：从右到左
TB / TD：从上到下
BT：从下到上
常用节点形状
flowchart LR
A[矩形]
B(圆角矩形)
C{判断}
D((圆形))
E[(数据库)]
对应源码：
```mermaid
flowchart LR
A[矩形]
B(圆角矩形)
C{判断}
D((圆形))
E[(数据库)]
```
带标签的箭头
flowchart LR
Query -->|RPC| Worker
Worker -->|Top-k| Controller
对应源码：
```mermaid
flowchart LR
Query -->|RPC| Worker
Worker -->|Top-k| Controller
```
子图
适合描述系统中的模块分组。
flowchart LR
subgraph ClientSide[Client]
A[Query]
end
subgraph ServerSide[Server]
B[Controller]
C[Worker]
end
A --> B --> C
对应源码：
```mermaid
flowchart LR
subgraph ClientSide[Client]
A[Query]
end
subgraph ServerSide[Server]
B[Controller]
C[Worker]
end
A --> B --> C
```
时序图
样例
sequenceDiagram
participant C as Client
participant M as Controller
participant W as Worker
C->>M: Query
M->>W: Search shard
W-->>M: Top-k
M-->>C: Final result
对应源码：
```mermaid
sequenceDiagram
participant C as Client
participant M as Controller
participant W as Worker
C->>M: Query
M->>W: Search shard
W-->>M: Top-k
M-->>C: Final result
```
时序图中的循环和条件
sequenceDiagram
Client->>Server: Request
alt cache hit
Server-->>Client: Cached result
else cache miss
Server->>DB: Query
DB-->>Server: Result
Server-->>Client: Result
end
对应源码：
```mermaid
sequenceDiagram
Client->>Server: Request
alt cache hit
Server-->>Client: Cached result
else cache miss
Server->>DB: Query
DB-->>Server: Result
Server-->>Client: Result
end
```
状态图
stateDiagram-v2
[*] --> Idle
Idle --> Running
Running --> Success
Running --> Failed
Success --> [*]
Failed --> Idle
对应源码：
```mermaid
stateDiagram-v2
[*] --> Idle
Idle --> Running
Running --> Success
Running --> Failed
Success --> [*]
Failed --> Idle
```
ER 图
erDiagram
USER ||--o{ NOTE : owns
NOTE }o--o{ TAG : has
对应源码：
```mermaid
erDiagram
USER ||--o{ NOTE : owns
NOTE }o--o{ TAG : has
```
类图
classDiagram
class Controller {
+search(query)
+merge(results)
}
class Worker {
+searchShard(query)
}
Controller --> Worker
对应源码：
```mermaid
classDiagram
class Controller {
+search(query)
+merge(results)
}
class Worker {
+searchShard(query)
}
Controller --> Worker
```
当前书库配置
[preprocessor.mermaid]
command = "mdbook-mermaid"
[output.html]
additional-js = ["mermaid.min.js", "mermaid-init.js"]
项目根目录的 mermaid-init.js 会根据 mdBook 当前主题选择 Mermaid 明暗主题；从亮色切到暗色或反向切换时，会通过刷新页面重新渲染 Mermaid。
Mermaid 适合什么
优先使用 Mermaid：
- 调用链；
- 服务间交互；
- 状态机；
- 数据模型关系；
- 逻辑流程；
- 架构模块关系。
如果重点是精确控制几何位置、框体尺寸和论文式示意图布局，优先考虑 Pikchr。