📊 Mermaid 流程圖 (Flowchart) 語法教學

🔗 官方資源：Mermaid.ai 官方網站與線上編輯器
從節點宣告、連線設計，到進階的子圖表佈局，完整掌握 Docs as Code 的精髓

第 1 課：製作目的與 Mermaid 功能簡介

🌟 為什麼要用 Mermaid？(Docs as Code 的精神)

Docs as Code (文件即程式碼) 是現代軟體工程的核心觀念。傳統用繪圖軟體畫圖容易遇到「排版耗時、不好修圖、無法版控」等問題。Mermaid 讓我們能用純文字快速寫出結構化圖表：

  • 零排版摩擦：系統自動計算節點與線條位置，不需要手動拖曳對齊。
  • 版本控制友善：純文字能輕鬆整合 Git，每一次的修改差異 (Diff) 一目了然。
  • 生態系無縫整合：GitHub, GitLab, Notion, Obsidian, VS Code 等工具皆原生支援渲染。

🛠️ Mermaid 核心功能與支援圖表種類

Mermaid 不僅僅能畫流程圖，它是一款全方位的圖表渲染引擎，主要功能特色包含：

  • 豐富的圖表類型：
    • 流程圖 (Flowchart)：表達系統邏輯、決策樹與架構流向（本指南重點）。
    • 時序圖 (Sequence Diagram)：描述 API 呼叫流程與物件間的互動時序。
    • 類別圖 (Class Diagram) & ER 圖：繪製面向對象架構與資料庫 Schema 模型。
    • 狀態圖 (State Diagram) & 甘特圖 (Gantt)：追蹤狀態轉移與專案時程進度。
    • 圓餅圖 (Pie) & 心智圖 (Mindmap)：快速進行資料統計與腦力激盪。
  • 靈活的主題與樣式自訂：支援自訂 CSS 樣式、classDef 類別套用，並內建 default, neutral, dark, forest 等多款主題。
  • 純 Web 即時渲染：只需引入單一 JavaScript 檔即可在瀏覽器端動態繪圖，無須依賴伺服器轉檔。

第 2 課：方向宣告與節點形狀大全 (Nodes)

📍 圖表宣告與排版方向

繪圖第一步，必須告訴系統這是流程圖，並指定方向：

  • graph TD：Top to Down (由上至下)。
  • graph LR：Left to Right (由左至右)。

🔄 節點 (Nodes) 的形狀控制

改變文字外圍的「括號」種類，就能直接決定節點形狀。

graph LR
    A[一般方形]
    B(圓角方形)
    C([膠囊形 / 端點])
    D[(圓柱體 / 資料庫)]
    E((圓形))
    F{菱形 / 判斷式}
    G>不對稱形狀]
    H[[雙線方形 / 子程式]]
graph LR A[一般方形] B(圓角方形) C([膠囊形 / 端點]) D[(圓柱體 / 資料庫)] E((圓形)) F{菱形 / 判斷式} G>不對稱形狀] H[[雙線方形 / 子程式]]

第 3 課：連線樣式與文字 (Edges)

graph LR
    A1 --> A2
    B1 --- B2
    C1 -.-> C2
    D1 ==> D2
    E1 <--> E2
    
    %% 線上加文字的方法
    F1 -->|步驟一| F2
    G1 -. "背景作業" .-> G2
    H1 == "強烈建議" ==> H2
graph LR A1 --> A2 B1 --- B2 C1 -.-> C2 D1 ==> D2 E1 <--> E2 F1 -->|步驟一| F2 G1 -. "背景作業" .-> G2 H1 == "強烈建議" ==> H2
連線種類 語法 (無文字) 語法 (含文字) 適用情境
實線箭頭 --> -->|文字| 一般流程、明確的下個步驟。
虛線箭頭 -.-> -. "文字" .-> 非同步處理、背景呼叫、選用流程。
粗實線箭頭 ==> == "文字" ==> 強調的主要流程、重要分支。
無箭頭實線 --- ---|文字| 單純的關聯、層級對等關係。

💡 線上文字標示的兩種等價寫法：

除了使用 | 包夾文字外，Mermaid 還支援另一種直接在線條中間寫字的方法，兩者效果完全一模一樣：

  • 寫法一 (使用 | 包夾)： A -->|"4. 查閱知識"| B
  • 寫法二 (線條拆開加引號)： A -- "4. 查閱知識" --> B

第 4 課：進階子圖表技巧 (Subgraphs)

📦 核心技巧：子圖表 (Subgraph) 與跨框指向

  • 定義子圖表： 使用 subgraph [ID] [顯示標題] ... end 就能將節點群組化。
  • 大框指向大框： 讓子圖表的 ID 直接連線，代表兩組系統整體的互動。
  • 特定節點跨框連線： 直接呼叫別的框內的節點 ID，線條就會自動穿透框架進行連接！
  • 大框內部的獨立方向： 在主圖由上至下 (TD) 佈局中，寫入 direction LR 即可產生水平區塊。
graph TD
    subgraph 區塊1 [系統前端]
        direction LR
        A1[輸入] --> A2[處理]
    end
    
    subgraph 區塊2 [系統後端]
        direction LR
        B1((資料庫A)) --- B2((資料庫B))
    end
    
    %% 大框指向大框
    區塊1 ==> 區塊2
    
    %% 特定節點跨框連線
    A2 -. "寫入" .-> B1
graph TD subgraph 區塊1 [系統前端] direction LR A1[輸入] --> A2[處理] end subgraph 區塊2 [系統後端] direction LR B1((資料庫A)) --- B2((資料庫B)) end 區塊1 ==> 區塊2 A2 -. "寫入" .-> B1

第 5 課：綜合實戰範例 (AI Agent 架構完全拆解)

現在，我們將前四課的知識組合起來，拆解以下這張專業的系統架構圖：

graph TD %% 1. 定義節點與群組 User(["使用者輸入 / 情境"]) subgraph Core ["AI Agent"] AI(("Antigravity/Claude/Codex")) Rules["AGENTS.md
(AI 長期記憶、全域鐵律)"] end subgraph Plugins ["Skill"] direction TB Skill{"SKILL.md
(任務 SOP 與指令)"} Scripts[["scripts/
(將制式流程轉為程式碼)"]] Resources("resources/
(模板：限制排版)") References("references/
(知識庫：提供術語)") %% 強制垂直排列避免圖表過寬 Scripts ~~~ Resources Resources ~~~ References end %% 2. 獨立宣告主流程連線 (避免干擾子圖表層級) User --> AI Rules -. "設定條件自動觸發" .-> AI AI -->|"1. 呼叫"| Skill Skill -->|"2. 觸發腳本"| Scripts Skill -->|"3. 套用模板"| Resources Skill -->|"4. 查閱知識"| References %% 3. 獨立宣告回傳連線 Scripts -. "回傳程式執行結果" .-> AI Resources -. "強制統一輸出格式" .-> AI References -. "補足專案專屬背景知識" .-> AI 
graph TD
    %% 1. 定義節點與群組
    User(["使用者輸入 / 情境"])

    subgraph Core ["AI Agent"]
        AI(("Antigravity/Claude/Codex"))
        Rules["AGENTS.md
(AI 長期記憶、全域鐵律)"]
    end

    subgraph Plugins ["Skill"]
        direction TB
        Skill{"SKILL.md
(任務 SOP 與指令)"}
        Scripts[["scripts/
(將制式流程轉為程式碼)"]]
        Resources("resources/
(模板：限制排版)")
        References("references/
(知識庫：提供術語)")
        
        %% 強制垂直排列避免圖表過寬
        Scripts ~~~ Resources
        Resources ~~~ References
    end

    %% 2. 獨立宣告主流程連線 (避免干擾子圖表層級)
    User --> AI
    Rules -. "設定條件自動觸發" .-> AI

    AI -->|"1. 呼叫"| Skill
    Skill -->|"2. 觸發腳本"| Scripts
    Skill -->|"3. 套用模板"| Resources
    Skill -->|"4. 查閱知識"| References

    %% 3. 獨立宣告回傳連線
    Scripts -. "回傳程式執行結果" .-> AI
    Resources -. "強制統一輸出格式" .-> AI
    References -. "補足專案專屬背景知識" .-> AI

💡 範例精華拆解與設計巧思：

  1. 節點宣告與連線分離：
    將所有的「節點建立」放在上方，而「跨群組的連線」集中在所有 subgraph 區塊的外部宣告。這種做法能避免 Mermaid 排版引擎將節點拉到同一水平線上，確保圖表維持由上到下的完美結構。
  2. 形狀語意的高度應用：
    • ([...]) 膠囊形：視覺上用來表示外部邊界（User）。
    • ((...)) 圓形：表示系統核心、大腦，聚焦視線。
    • {...} 菱形：表示邏輯中樞或分支點（Skill 分派任務）。
    • [[...]] 雙線方形：表示實際執行的腳本。
  3. 實線與虛線的邏輯區分：
    主流程（主動呼叫）使用了實線 -->；而被動觸發或回傳，使用了虛線 -.->，這點讓圖表的資料流向極具層次感。

第 6 課：補充進階語法與實用技巧

除了前面的基礎與進階佈局外，Mermaid 還支援許多能讓圖表更有彈性與互動性的進階語法：

1. 多點一對多 / 多對多快速連線 (&)

不需要寫多行連線，利用 & 符號就能在一行內同時連接多個節點：

graph LR
    A & B --> C & D
graph LR A & B --> C & D

2. 連線長度控制 (拉長距離)

當圖表太密擠在一起時，增加連線中的破折號 - 數量，就能強制拉長節點間的距離：

graph TD
    A[標準距離] --> B
    C[拉長兩倍距離] ---> D
    E[拉長三倍距離] ----> F
graph TD A[標準距離] --> B C[拉長兩倍距離] ---> D E[拉長三倍距離] ----> F

3. 自訂顏色與 CSS 樣式語法 (style, classDef & linkStyle)

在 Mermaid 中，您可以為單一節點、子圖表大框，甚至連線單獨自訂顏色：

屬性名稱 說明 範例設定
fill 節點或大框的背景顏色 fill:#f3e8ff 或 fill:lightblue
stroke 邊框或連線的線條顏色 stroke:#7c4dff 或 stroke:red
stroke-width 邊框或連線的線條粗細 stroke-width:2px
color 節點內部的文字顏色 color:#ffffff 或 color:#333
  • ① 單一節點/大框直寫變色 (style)：
    style User fill:#e0f2fe,stroke:#0284c7 (單一節點)
    style Core fill:#fffde7,stroke:#d4e157 (子圖表大框)
  • ② 模組化共用類別變色 (classDef & class)：
    定義：classDef 類別名 fill:#顏色,stroke:#顏色; ➔ 套用：class A,B 類別名;
  • ③ 連線/箭頭單獨變色 (linkStyle)：
    linkStyle 0 stroke:#ef4444,stroke-width:2px; (第 1 條連線變紅)
    linkStyle default stroke:#3b82f6; (所有連線預設變藍) 
graph LR
    A[單一自訂] --> B[危險節點] --> C[成功節點]
    
    %% 1. 單一節點直寫變色 (style)
    style A fill:#e0f2fe,stroke:#0284c7,stroke-width:2px,color:#0369a1
    
    %% 2. 定義共用類別 (classDef)
    classDef danger fill:#fee2e2,stroke:#ef4444,color:#991b1b;
    classDef success fill:#dcfce7,stroke:#22c55e,color:#166534;
    
    %% 套用類別 (class)
    class B danger;
    class C success;

    %% 3. 連線單獨變色 (linkStyle)
    linkStyle 0 stroke:#ef4444,stroke-width:2px;
    linkStyle 1 stroke:#22c55e,stroke-width:2px;
graph LR A[單一自訂] --> B[危險節點] --> C[成功節點] style A fill:#e0f2fe,stroke:#0284c7,stroke-width:2px,color:#0369a1 classDef danger fill:#fee2e2,stroke:#ef4444,color:#991b1b; classDef success fill:#dcfce7,stroke:#22c55e,color:#166534; class B danger; class C success; linkStyle 0 stroke:#ef4444,stroke-width:2px; linkStyle 1 stroke:#22c55e,stroke-width:2px;

4. 超連結與點擊事件 (click) 與程式註解 (%%)

  • 超連結設定： 使用 click 節點名稱 "網址" "懸浮提示"，點擊圖表中的節點就能跳轉網頁。
  • 程式碼註解： 以 %% 開頭的行數為註解，渲染時會自動忽略，適合用於撰寫說明備忘。
graph LR
    %% 這是一行不會渲染出來的備註註解
    Google[點我前往 Google]
    click Google "https://www.google.com" "前往 Google 首頁" _blank
graph LR %% 這是一行不會渲染出來的備註註解 Google[點我前往 Google] click Google "https://www.google.com" "前往 Google 首頁" _blank