Mermaid 圖表教學:用文字畫流程圖、循序圖與甘特圖

Mermaid 是一種「用文字描述圖表」的語法。你不用拖拉方塊、也不用另外存圖片,只要在 Markdown 裡寫幾行文字,閱讀器就會自動畫出流程圖。文字版的圖表好修改、好版本控管,GitHub、GitLab、Notion 與墨閱都支援。

怎麼在 Markdown 裡放 Mermaid

用三個反引號開啟程式碼區塊,語言標註為 mermaid:

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

把這段放進 .md 檔,用墨閱開啟,就會看到一張由左到右的流程圖。點選圖表右上角的「放大檢視」可以縮放細節。

流程圖 flowchart

第一行宣告方向:TD(上到下)或 LR(左到右)。節點用不同括號決定形狀:

flowchart TD
    A[方形節點] --> B(圓角節點)
    B --> C{判斷}
    C -->|是| D[[子流程]]
    C -->|否| E((圓形))
  • --> 是箭頭,--- 是無箭頭連線,-.-> 是虛線。
  • |文字| 放在箭頭上,用來標示條件。
  • 節點代號(A、B、C)只要不重複即可,畫面上顯示的是括號裡的文字。

循序圖 sequenceDiagram

適合描述系統之間、使用者與服務之間的互動順序:

sequenceDiagram
    participant U as 使用者
    participant S as 伺服器
    U->>S: 送出登入資料
    S-->>U: 回傳登入結果
    Note over U,S: 全程使用 HTTPS

->> 是實線箭頭(請求),-->> 是虛線箭頭(回應)。Note over 可以加註解。

甘特圖 gantt

專案時程一目了然:

gantt
    title 網站改版計畫
    dateFormat YYYY-MM-DD
    section 設計
    需求訪談 :a1, 2025-01-06, 5d
    介面設計 :after a1, 7d
    section 開發
    前端開發 :2025-01-20, 10d
    測試上線 :5d

圓餅圖 pie

pie title 每日時間分配
    "工作" : 8
    "睡眠" : 7
    "閱讀" : 2
    "其他" : 7

狀態圖 stateDiagram

stateDiagram-v2
    [*] --> 草稿
    草稿 --> 審核中: 送出
    審核中 --> 已發布: 核准
    審核中 --> 草稿: 退回
    已發布 --> [*]

常見錯誤與排除

  • 圖表沒有出現:確認程式碼區塊標註的是 mermaid,而且第一行有圖表類型(flowchart、sequenceDiagram 等)。
  • 文字含特殊符號:節點文字包含括號、冒號時,用雙引號包起來,例如 A["價格 (含稅)"]。
  • 方向寫錯:flowchart 後面只能接 TB、TD、BT、RL、LR。
  • 墨閱遇到錯誤時,會保留原始碼並顯示錯誤原因,其餘內容仍可正常閱讀。

小技巧

  • 圖表太大時,改用 LR 方向通常比較好讀。
  • 同一份文件可以放多張圖表,墨閱一份文件最多繪製 40 張。
  • 切換到「夜讀」主題,圖表配色也會跟著改變;匯出 PDF 時則會自動改用淺色。

想看實際效果?在墨閱首頁按「圖表・公式・執行範例」,就能開啟一份含 Mermaid 圖表的示範文件。