Mermaid 語法速查（Syntax Reference）

本頁是語法學習 / 查詢的入口，範本庫是複製即用的起點，語法速查教你怎麼改。

在哪裡渲染

公司主要用途：

• MkDocs Material（secs-docs.gathertech.com.tw）— 原生支援
• Docusaurus（gathertech-docs）— 原生支援（注意 MDX 跳脫）
• GitHub Markdown（README、PR 描述）— 原生支援
• Notion / Obsidian / VS Code preview — 原生支援

Mermaid 只需程式碼區塊標示 mermaid：

```mermaid
flowchart LR
    A[開始] --> B[結束]
```

---

1. Flowchart（最常用）

1.1 方向

宣告	意義
flowchart TB or TD	Top → Bottom（階層／分層用這個）
flowchart BT	Bottom → Top（較少用）
flowchart LR	Left → Right（流程／時間序用這個）
flowchart RL	Right → Left（阿拉伯／希伯來文用）

1.2 節點形狀

何時用哪種：

形狀	用途
[矩形]	一般步驟、模組（最常用）
(圓角矩形)	子流程、軟性動作
{菱形}	決策點（必然有 Yes/No 分支）
[(圓柱)]	資料庫 / 資料儲存
((圓形))	連接點、起點
[[雙框]]	子系統 / 外部呼叫

1.3 連線（箭頭）

語法	意義
-->	實線箭頭（最常用）
---	實線無箭頭
-.->	虛線箭頭（非同步／鬆散關連）
==>	粗線箭頭（強調）
~~~	隱形連接（排版用）

邊的文字（label）：

1.4 Subgraph（分組）

分組內方向：

subgraph Name["Display Name"]
    direction LR     <!-- 可覆寫外層方向 -->
    A --> B
end

1.5 樣式（重點節點標色）

常用色（建議）：

• 成功／正常：fill:#c8e6c9
• 錯誤／警告：fill:#ffcdd2
• 強調／注意：fill:#fff9c4
• 外部／次要：fill:#e3f2fd

1.6 Class（批次套樣式）

---

2. Sequence Diagram

2.1 參與者

• actor：人形 icon（給使用者／客戶）
• participant：方框（給系統／服務）
• as XX：顯示名稱

2.2 訊息類型

語法	意義
A->>B: msg	同步請求（實線）
A-->>B: reply	回應（虛線）
A-)B: msg	非同步（fire-and-forget）
A-xB: msg	失敗訊息（X 標記）
A->>A: self	自我呼叫

2.3 註解與分組

2.4 控制流程

條件分支 alt/else

alt 條件 A
    A->>B: do X
else 條件 B
    A->>B: do Y
else 條件 C
    A->>B: do Z
end

可選 opt（相當於只有 if 沒有 else）

opt 可能發生時
    A->>B: maybe
end

迴圈 loop

loop 每 10 秒
    A->>B: heartbeat
end

平行 par/and

par 同時做兩件事
    A->>B: task 1
and
    A->>C: task 2
end

2.5 啟動狀態（activation）

+ 啟動、- 停止，可視化 B 忙碌期間。

---

3. State Diagram（stateDiagram-v2）

用 v2，不要用舊的 stateDiagram。

3.1 基本語法

• [*] 起始 / 終止
• --> 狀態轉換
• : 文字 觸發條件

3.2 複合狀態（巢狀）

3.3 平行狀態（fork / join）

多條從 [*] 出去 = 平行啟動。多條到 [*] 進來 = 等全部完成才繼續。

3.4 Guard Condition

STATE1 --> STATE2 : event<br/>[guard condition]

用 <br/> 換行寫 guard。

3.5 Note

note right of StateName
    這是說明
    可以多行
end note

---

4. ER Diagram

4.1 關係符號

符號	意義
`
`
`
`
}|--|{	多對多

4.2 範例

4.3 屬性標記

• PK — Primary Key
• FK — Foreign Key
• UK — Unique Key

---

5. Class Diagram

5.1 基本語法

Access modifier：

• + public
• - private
• # protected
• ~ package/internal

5.2 關係符號

符號	意義
`<	--`
`<	..`
*--	組合（composition，強依賴）
o--	聚合（aggregation，弱依賴）
-->	關聯（association）
..>	依賴（dependency）

註：表中 < 在 Mermaid 原始碼中是左尖括號，用 HTML entity 顯示是為了避開 MDX 將 < 當成 JSX 標籤起始的解析錯誤。

5.3 範例

---

6. Gantt

6.1 基本語法

6.2 狀態標記

標記	顯示
done	灰色（已完成）
active	藍色（進行中）
crit	紅色（關鍵路徑）
milestone	菱形里程碑

6.3 依賴

任務 B :a2, after a1, 5d           <!-- 依賴 a1 -->
任務 D :a4, after a2 a3, 3d        <!-- 同時依賴 a2 和 a3 -->

---

7. 其他 Diagram Types（簡介）

7.1 Pie Chart

7.2 Journey

分數 1-5（5 最好）。可多 actor 共享一步驟。

7.3 gitGraph

7.4 Mindmap

7.5 Timeline

---

8. 通用功能

8.1 註解（不顯示）

%%這是註解，不會出現在圖上
%% 可以單行或多行

8.2 跳脫特殊字元

當文字含 "、#、<、> 等：

A["他說「很好」"]          <!-- 中文引號不用跳脫 -->
B["含 <br/> 換行"]         <!-- HTML 標籤可用 -->
C["含 \"雙引號\""]         <!-- 反斜線跳脫 -->

8.3 標題

flowchart TB
    title 我的架構圖       <!-- ⚠️ 部分圖型支援，有些不支援 -->

建議：標題寫在 Mermaid 外面的 markdown（## 架構圖 然後接 mermaid block）。

8.4 換行

用 <br/> 在節點文字中：

A["第一行<br/>第二行"]

---

9. 常見錯誤與解法

9.1 MDX 解析錯誤（Docusaurus 特有）

錯誤：Unexpected end of file in expression, expected a corresponding closing brace for {

原因：Inline code（單 backtick）內有未配對的 {，MDX 把它當 JSX 表達式。

解法：用 HTML entity {（{）、}（}）。

Fenced code block（triple backtick）不受影響。

9.2 節點 ID 衝突

如果兩個 subgraph 用相同 ID：

subgraph A
    Node1
end
subgraph B
    Node1         <!-- ❌ 衝突 -->
end

解法：不同 subgraph 內的節點 ID 必須唯一。用前綴：

subgraph A
    A_Node1
end
subgraph B
    B_Node1
end

9.3 特殊字元在節點 ID

節點 ID 不能有空格、連字號以外的符號。

❌  my-node --> other-node
✅  myNode --> otherNode
✅  my_node --> other_node

顯示文字可有空格（在 [] 裡）：

myNode["My Node with Space"]

9.4 長箭頭斷開

A --------> B       <!-- ✅ 箭頭越長，間距越寬 -->
A ----> B           <!-- ✅ 中等間距 -->
A --> B             <!-- ✅ 緊密 -->

加減 - 的數量可調間距。

---

10. 速查總結

需求	關鍵字
系統架構	flowchart TB + subgraph
時序 / API 流程	sequenceDiagram + alt/opt/loop
狀態轉換	stateDiagram-v2
資料表關聯	erDiagram + ||--o{
類別繼承	classDiagram + <|--
專案時程	gantt + section
使用者體驗	journey
Git 分支	gitGraph

---

11. 學習資源

官方（最權威）

• Mermaid 官方文件：mermaid.js.org
• Live Editor（線上試寫）：mermaid.live
• GitHub：github.com/mermaid-js/mermaid

公司內部

• Mermaid 範本庫 — 複製即用
• PM repo docs/shared/guides/Mermaid-Usage-Guide.md — 品質標準
• PM repo docs/shared/agent-rules/COMMON-RULES.md — 規範

快速試寫

不確定語法？打開 mermaid.live，左邊貼程式碼，右邊即時看結果。錯了會顯示錯誤訊息。

---

12. 實戰建議

1. 先從範本庫複製，不要從零寫
2. 不熟的語法先到 Live Editor 試寫
3. 複雜圖拆成多張（> 30 節點就太多）
4. 節點文字寫完整句子，不用代號（A、B、C）
5. 邊有 label，特別是決策分支
6. 提交前在目標平台預覽（Docusaurus 或 MkDocs 可能有差異）