القائمة
當使用者要用 Mermaid 視覺化流程、時間關係或資訊結構時使用。協助選擇圖表類型，並處理中文相容與產出規則。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | mermaid-diagram |
| description | 當使用者要用 Mermaid 視覺化流程、時間關係或資訊結構時使用。協助選擇圖表類型，並處理中文相容與產出規則。 |
| version | 2026.3.9 |
| metadata | {"short-description":"Mermaid 圖表規劃、選型、中文相容與產出指引","openclaw":{"emoji":"📊"}} |
| 需求 | 使用類型 | 中文支援 |
|---|---|---|
| 程序/流程 | flowchart | 完整支援 |
| 系統互動/API | sequenceDiagram | 完整支援 |
| 物件導向 | classDiagram | 方法名建議英文 |
| 狀態機 | stateDiagram-v2 | 完整支援 |
| 資料庫設計 | erDiagram | 欄位名需英文 |
| 時程規劃 | gantt | 完整支援 |
| 比例分配 | pie | 完整支援 |
| 概念發散 | mindmap | 完整支援 |
| 時間事件 | timeline | 完整支援 |
| 矩陣分析 | quadrantChart | 完整支援，點名稱含特殊符號需加引號 |
| 系統架構（新版） | architecture-beta | 僅 v11+，標籤支援中文，ID 必須英文 |
| 看板/Sprint 管理 | kanban | 僅 v11.4+，標籤支援中文，ID 必須英文 |
| Git 歷史 | gitgraph | branch 名建議英文 |
節點文字含有 ()[]{}:, 等符號時，必須用雙引號包裹整個標籤：
# 錯誤
A[用戶(User)] --> B
# 正確
A["用戶(User)"] --> B
# 錯誤
A[前端: React] --> B
# 正確
A["前端: React"] --> B
# 正確
erDiagram
用戶 {
int id PK "主鍵"
string name "姓名"
string email "電子郵件"
}
# 錯誤 - 欄位名不能用中文
erDiagram
用戶 {
int 編號 PK
}
class 的方法名（method）建議用英文，屬性類型也用英文，class 名稱可用中文：
# 推薦（屬性名英文，class 名中文）
classDiagram
class 用戶 {
+String name
+int age
+login() bool
}
# 可能有解析問題（避免中文方法名）
classDiagram
class 用戶 {
+登入() bool
}
# 有空格時用 as 別名
sequenceDiagram
participant FE as 前端系統
participant BE as 後端 API
FE->>BE: 發送請求
# 無空格時可直接用中文
sequenceDiagram
participant 前端
participant 後端
前端->>後端: 呼叫API
# 正確：commit 訊息可用中文，branch 名用英文
gitgraph
commit id: "初始化專案"
branch feature/login
commit id: "新增登入功能"
checkout main
merge feature/login id: "合併登入功能"
# 不建議：中文 branch 名
gitgraph
branch 登入功能分支
邊（edge）上的文字完整支援中文，無需引號：
flowchart TD
A -->|成功| B
A -->|失敗| C
A -- 驗證中 --> D
gantt
title 第一季開發計畫
dateFormat YYYY-MM-DD
section 規劃階段
需求分析 :a1, 2024-01-01, 5d
UI設計 :a2, after a1, 7d
這些是 Mermaid 解析器的關鍵字，若出現在節點 ID 中會直接導致 Parse error。
| 保留字 | 用途 | 衝突情境 | 解法 |
|---|---|---|---|
end | 結束 subgraph 區塊 | 節點 ID 為 end | 改用 End、END、或加引號標籤 |
subgraph | 宣告子圖 | 節點 ID 含此字 | 用不同 ID，標籤加引號 |
graph | 圖表宣告 | 節點 ID 為 graph | 用不同 ID |
direction | 子圖方向 | 節點 ID 為 direction | 用不同 ID |
default | 預設 classDef | 節點 ID 為 default | 用不同 ID |
style | 節點樣式 | 節點 ID 為 style | 用不同 ID |
classDef | 定義 class | 節點 ID 含此字 | 用不同 ID |
class | 指定 class | 節點 ID 為 class | 用不同 ID |
click | 點擊事件 | 節點 ID 為 click | 用不同 ID |
linkStyle | 邊樣式 | 節點 ID 含此字 | 用不同 ID |
o (首字) | 圓形邊端點 | 節點 ID 以 o 開頭，前面有 --- | 加空格：--- oNode 或改大寫 O |
x (首字) | 叉形邊端點 | 節點 ID 以 x 開頭，前面有 --- | 加空格：--- xNode 或改大寫 X |
# 錯誤範例：end 作為節點 ID
flowchart TD
start --> process --> end
# 正確解法 1：大寫
flowchart TD
start --> process --> END
# 正確解法 2：不同 ID + 中文標籤
flowchart TD
s[開始] --> p[處理] --> e[結束]
# 正確解法 3：引號強制為標籤（ID 不同）
flowchart TD
n_start --> n_process --> n_end["end"]
sequenceDiagram 的保留字不能作為 participant 名稱（無引號時）：
| 保留字 | 作用 |
|---|---|
participant | 宣告參與者 |
actor | 宣告人形參與者 |
activate | 啟動生命線框 |
deactivate | 結束生命線框 |
note | 加備註 |
over | note 修飾詞 |
loop | 迴圈區塊 |
alt | 條件分支 |
else | alt 的分支 |
opt | 可選區塊 |
par | 並行區塊 |
and | par 的分支 |
end | 結束區塊 |
autonumber | 自動編號 |
title | 圖表標題 |
as | 別名關鍵字 |
# 錯誤：participant 名稱使用保留字
sequenceDiagram
participant loop
participant end
# 正確：用 as 別名避開保留字
sequenceDiagram
participant L as 迴圈服務
participant E as 結束處理器
| 保留字 | 作用 |
|---|---|
state | 宣告複合狀態 |
note | 狀態備註 |
as | 狀態別名 |
end note | 結束備註 |
[*] | 起始/終止偽狀態 |
choice | 條件偽狀態 |
fork / join | 並行分叉/合流 |
concurrency | 並行狀態 |
| 保留字 | 作用 |
|---|---|
title | 圖表標題 |
dateFormat | 日期格式 |
axisFormat | 軸顯示格式 |
tickInterval | 刻度間距 |
excludes | 排除日期 |
includes | 包含日期 |
section | 區段 |
done | 任務狀態 |
active | 任務狀態 |
crit | 關鍵路徑 |
milestone | 里程碑 |
after | 相對時間關鍵字 |
中文本身不含保留字，但要注意：
- 節點 ID（空白前的識別子）不能是保留字
- 節點標籤（括號內或引號內的顯示文字）可以是任意中英文
- ID 與標籤可以分開：
end_node["結束"]，ID 用英文，標籤用中文
將含有問題字元的整段標籤用 "..." 包起來：
flowchart TD
A["使用者 (User)"] --> B["系統:後端"]
C["100% 完成"] --> D["A & B 同時"]
適用字元：( ) [ ] { } : , / \ & % < >
#name; 或 #數字;）Mermaid 使用自訂的逸出格式（非標準 HTML &name;）：
flowchart LR
A["引號: #quot;"] --> B["小於: #lt;"]
C["大於: #gt;"] --> D["& 符號: #amp;"]
E["愛心: #9829;"] --> F["版權: #169;"]
| 字元 | Mermaid 逸出碼 | 說明 |
|---|---|---|
" | #quot; | 雙引號（在引號內文字用） |
< | #lt; | 小於 |
> | #gt; | 大於 |
& | #amp; | &符號 |
# | #35; | 井號（十進位 35） |
© | #169; | 版權符號 |
♥ | #9829; | 愛心（十進位） |
; | #59; | 分號 |
格式規則：
#名稱;（HTML 具名實體）或#十進位數字;（十進位字元碼） 注意：此格式不是&name;（標準 HTML），而是#name;
| 原字 | 替代方案 |
|---|---|
end | END、End、結束、完成 |
(內文) | ["內文"] 改用方括號 + 引號 |
/ | #47; 或改述文字 |
\ | #92; 或改述文字 |
" | #quot; |
永遠使用短英文/數字作為 ID，只讓標籤呈現中文或特殊文字：
# 最安全的寫法：ID 完全避開保留字與特殊字元
flowchart TD
n1["開始 (Start)"] --> n2{"是否有效? (Valid?)"}
n2 -->|是 Yes| n3["處理 (Process)"]
n2 -->|否 No| n4["錯誤 (Error)"]
n3 --> n5["結束 (End)"]
n4 --> n5
用反引號包裹，支援粗體、斜體、換行，且會自動處理部分逸出：
flowchart TD
A["`**開始**
第一行
第二行`"] --> B["`*斜體標籤*`"]
注意：Markdown 字串模式在部分渲染環境（如舊版 GitHub）可能不支援
\nMermaid 的節點標籤是單行語法，直接插入換行字元 \n 或 Python/JS 的 \\n 字串不會渲染成視覺換行，會直接破壞 Parse。
# 絕對錯誤：\n 不是換行
flowchart TD
A["第一行\n第二行"] --> B
# 絕對錯誤：literal newline 在標籤內
flowchart TD
A["第一行
第二行"] --> B
<br> 標籤（最通用，htmlLabels: true 預設）在雙引號標籤內使用 <br> 或 <br/> 插入換行：
flowchart TD
A["第一行<br>第二行<br>第三行"] --> B["使用者<br>登入系統"]
C["錯誤訊息：<br>密碼不正確<br>請重試"] --> D
<br>與<br/>在 Mermaid 中效果相同，但部分外部 SVG 解析器偏好<br/>
重要：
<br>僅在htmlLabels: true（預設值）時有效。若環境設定htmlLabels: false，必須改用方法 2。
用 "``...``" 包裹，在字串內直接用真實換行（按 Enter）：
flowchart TD
A["`第一行
第二行
第三行`"] --> B
語法詳解：
"..." 包裹` 開頭` 再寫閉合引號 "flowchart LR
A["`**系統登入**
請輸入帳號
和密碼`"] --> B{"`是否
已驗證?`"}
B -- 是 --> C["`進入
首頁`"]
Markdown 字串額外好處：支援 **粗體**、*斜體*、自動折行
| 圖表類型 | 節點換行方式 | 備註 |
|---|---|---|
| flowchart | <br> 或 Markdown 字串 | 最常見需求 |
| sequenceDiagram | 訊息文字不支援換行 | 縮短文字或拆多行訊息 |
| classDiagram | 屬性/方法各佔一行（原生） | 無需額外換行 |
| stateDiagram-v2 | 不支援換行 | 縮短狀態名稱 |
| erDiagram | 欄位各佔一行（原生） | 無需額外換行 |
| gantt | section/task 各佔一行（原生） | 無需額外換行 |
| mindmap | 不支援節點內換行 | 縮短節點文字 |
| timeline | 每個事件可多條（各佔行） | 原生支援多事件 |
# 正確：<br> 在引號標籤內
flowchart TD
A["資料驗證失敗<br>請檢查輸入格式"] --> B
# 正確：Markdown 字串換行
flowchart TD
A["`資料驗證失敗
請檢查輸入格式`"] --> B
# 錯誤：未加引號直接用 <br>（會被解析為節點形狀語法衝突）
flowchart TD
A[資料驗證失敗<br>請檢查] --> B
# 錯誤：用 \n（不是換行，是字面文字）
flowchart TD
A["資料驗證\n請檢查"] --> B
這些是在無引號時會直接觸發 Parse error 的字元：
| 字元 | 問題原因 | 引號內安全? | 逸出碼 |
|---|---|---|---|
( ) | 節點形狀語法（圓角括號） | 是 | #40; #41; |
[ ] | 節點形狀語法（矩形） | 是（但需引號） | #91; #93; |
{ } | 節點形狀語法（菱形） | 是 | #123; #125; |
> | 節點形狀語法（非對稱形） | 是 | #gt; |
: | 邊標籤分隔符 | 是 | #58; |
" | 引號本身 | 否（用逸出碼） | #quot; |
' | 部分情境衝突 | 是 | #39; |
@ | v11 新語法 @{...} 觸發 | 是 | #64; |
/ | 斜線節點形狀（平行四邊形） | 是 | #47; |
\ | 反斜線節點形狀 | 是 | #92; |
& | HTML entity 衝突 | 是 | #amp; |
| ` | ` | 邊標籤語法 `--> | 文字 |
# | Mermaid entity 觸發符 | 是 | #35; |
% | 註解符 %% | 是 | #37; |
- | 邊連線符（-->） | 通常安全 | #45; |
; | 陳述句結束符 | 是 | #59; |
萬用原則：凡含上列任何符號的標籤，一律加雙引號 "..." 包裹。
中文標點字元（如 、：，。）在舊版 Mermaid 會觸發 Parse error，現代版（v9+）已改善，但仍有風險：
| 中文字元 | 風險等級 | 說明 | 解法 |
|---|---|---|---|
， 全形逗號 | 中 | 部分版本誤解析為分隔符 | 加雙引號 |
。 句號 | 低 | 通常安全，但句尾可能影響 | 加雙引號 |
： 全形冒號 | 高 | 被解析為邊標籤分隔符 | 加雙引號或改用 #65306; |
、 頓號 | 中 | 部分版本有問題 | 加雙引號 |
！ 全形驚嘆號 | 低 | 通常安全 | 加雙引號預防 |
？ 全形問號 | 低 | 通常安全 | 加雙引號預防 |
「」『』 書名號/引號 | 中 | 括號類字元有風險 | 一律加雙引號 |
【】 方頭括號 | 高 | 形狀語法衝突 | 一律加雙引號 |
《》〈〉 書名號 | 中 | 部分版本有問題 | 一律加雙引號 |
… 省略號 | 低 | 通常安全 | 加雙引號預防 |
— 破折號 | 低 | 通常安全 | 加雙引號預防 |
中文標點黃金規則：只要節點標籤含有任何中文標點，一律用雙引號包裹。
# 危險：全形冒號在無引號標籤內
flowchart TD
A[輸入：帳號密碼] --> B
# 安全：加引號
flowchart TD
A["輸入：帳號密碼"] --> B
# 危險：全形括號
flowchart TD
A[確認【重要】訊息] --> B
# 安全：加引號
flowchart TD
A["確認【重要】訊息"] --> B
連線上的文字（-->|文字| 或 -- 文字 -->）規則略有不同：
# 正確：pipe 語法（文字兩側有 |）
flowchart TD
A -->|"成功：進入系統"| B
A -->|"否（失敗）"| C
# 正確：dash 語法（文字兩側有空格）
flowchart TD
A -- "驗證：通過" --> B
# 錯誤：pipe 語法文字含有 | 符號
flowchart TD
A -->|A|B 選擇| B
# 正確：改用引號 + 逸出
flowchart TD
A -->|"A#124;B 選擇"| B
%% 註解的標點限制# 正確：純文字註解
flowchart TD
%% 這是一般中文註解
A --> B
# 注意：%% 之後的文字不能含有圖表語法衝突字元
%% 若含有 --> 或 [] 可能有問題，建議保持簡單文字
flowchart TD
A(["開始（Start）"]) --> B{"是否已登入？"}
B -->|"是：已驗證"| C["進入首頁<br>歡迎使用系統"]
B -->|"否：未驗證"| D["顯示錯誤訊息<br>請重新登入"]
D --> E["輸入：帳號/密碼"]
E --> F{"格式是否正確？<br>（英數字8位以上）"}
F -->|"正確"| G["送出驗證"]
F -->|"錯誤【格式不符】"| E
G --> B
C --> H(["結束（End）"])
flowchart TD
A([開始]) --> B{使用者已登入?}
B -- 是 --> C[顯示首頁]
B -- 否 --> D[跳轉登入頁]
D --> E[輸入帳號密碼]
E --> F{驗證成功?}
F -- 是 --> C
F -- 否 --> G[顯示錯誤]
G --> D
C --> H([結束])
方向選擇：
節點形狀：
sequenceDiagram
autonumber
actor 使用者
participant 前端
participant 後端
participant DB as 資料庫
使用者->>前端: 送出表單
前端->>後端: POST /api/login
後端->>DB: 查詢用戶
DB-->>後端: 返回資料
後端-->>前端: 200 OK + JWT
前端-->>使用者: 登入成功
Note over 前端,後端: HTTPS 加密傳輸
箭頭類型：
stateDiagram-v2
[*] --> 草稿
草稿 --> 審核中 : 提交審核
審核中 --> 已發布 : 審核通過
審核中 --> 草稿 : 退回修改
已發布 --> 已下架 : 手動下架
已下架 --> [*]
note right of 審核中
等待主管批准
end note
classDiagram
class User {
+int id
+String name
+String email
+login() bool
+logout()
}
class Order {
+int id
+float totalAmount
+cancel()
}
User "1" --> "0..*" Order : 建立
erDiagram
USER {
int id PK "主鍵"
string name "姓名"
string email "電子郵件"
}
ORDER {
int id PK "訂單編號"
int user_id FK "用戶外鍵"
float total "總金額"
}
USER ||--o{ ORDER : "下訂"
gantt
title 2024 年產品開發路線圖
dateFormat YYYY-MM-DD
excludes weekends
section Q1 規劃
市場研究 :done, a1, 2024-01-01, 2024-01-15
需求訪談 :done, a2, after a1, 10d
功能規格書 :active, a3, after a2, 7d
section Q2 開發
前端實作 : b1, 2024-04-01, 30d
後端 API : b2, 2024-04-01, 30d
整合測試 :crit, b3, after b1, 14d
section Q3 上線
正式上線 :milestone, c2, 2024-07-28, 0d
pie showData
title 各部門人力占比
"工程部" : 45
"產品部" : 25
"設計部" : 15
"行銷部" : 10
"其他" : 5
mindmap
root((產品策略))
市場定位
目標用戶
企業客戶
個人用戶
競爭優勢
功能規劃
核心功能
進階功能
營運計畫
上市時程
行銷策略
timeline
title 公司發展歷程
2019 : 公司成立
: 天使輪融資完成
2020 : MVP 產品上線
2021 : A 輪融資 5000 萬
2022 : 海外市場佈局
2023 : B 輪融資 2 億
最低版本：v9.4+ 平台相容性：中（需要 v9.4+，Obsidian 舊版不支援）
quadrantChart
title <標題>
x-axis <左端標籤> --> <右端標籤>
y-axis <下端標籤> --> <上端標籤>
quadrant-1 <右上象限標籤> ← 右上
quadrant-2 <左上象限標籤> ← 左上
quadrant-3 <左下象限標籤> ← 左下
quadrant-4 <右下象限標籤> ← 右下
<點名稱>: [x值, y值]
象限編號對應位置（常見搞混點）：
quadrant-2 (左上) | quadrant-1 (右上)
─────────────────────────────────────
quadrant-3 (左下) | quadrant-4 (右下)
[0.5, 0.5] 恰好在中心quadrantChart
title 功能優先級矩陣（業務價值 vs 開發成本）
x-axis 低開發成本 --> 高開發成本
y-axis 低業務價值 --> 高業務價值
quadrant-1 規劃做（大工程高價值）
quadrant-2 快速做（小工程高價值）
quadrant-3 重新評估（大工程低價值）
quadrant-4 暫緩做（小工程低價值）
"用戶 SSO 登入": [0.3, 0.85]
深色模式: [0.2, 0.3]
"AI 推薦引擎": [0.85, 0.8]
"報表 PDF 匯出": [0.4, 0.7]
多語系支援: [0.75, 0.5]
聊天機器人: [0.9, 0.35]
通知中心: [0.35, 0.65]
| 問題 | 原因 | 解法 |
|---|---|---|
| 點名稱含括號/冒號渲染失敗 | 冒號是座標分隔符 | 用雙引號包裹整個名稱 "名稱(說明): [x,y]" |
| 象限標籤方向搞錯 | quadrant-1~4 不是直覺的順序 | 記住：1=右上、2=左上、3=左下、4=右下 |
| x-axis / y-axis 箭頭方向錯 | --> 代表增加方向 | 左邊寫「低」，右邊寫「高」 |
| 點全部堆在中間 | 座標分布不均 | 刻意將座標分散到 0.1–0.4 與 0.6–0.9 |
最低版本：v11.0+ 平台相容性：低（僅新版環境支援，Obsidian / GitLab 多數不支援）
優先考慮：若需要廣泛相容，請改用
flowchart LR + subgraph。architecture-beta 適合在 Claude Artifacts、最新版 mermaid-live-editor 等確定 v11+ 的環境使用。
| 元素 | 關鍵字 | 說明 |
|---|---|---|
| 群組（邊框容器） | group | 代表一個部署環境、VPC、網段 |
| 服務（節點） | service | 代表一個服務、元件、資源 |
| 連線 | :方向 --> 方向: | 用方向符號連接兩個 service |
architecture-beta
group <groupId>(<icon>)[<標籤>]
group <groupId>(<icon>)[<標籤>] in <parentGroupId> ← 巢狀群組
service <serviceId>(<icon>)[<標籤>]
service <serviceId>(<icon>)[<標籤>] in <groupId> ← 放入群組
<serviceId>:<方向> --> <方向>:<serviceId>
L 左、R 右、T 上、B 下A:R --> L:B 表示從 A 的右側連到 B 的左側| Icon 名稱 | 代表意義 |
|---|---|
cloud | 雲端服務 |
server | 伺服器 |
database | 資料庫 |
disk | 磁碟/儲存 |
internet | 網際網路/用戶端 |
user | 使用者 |
gateway | 閘道 |
完整 icon 清單：https://mermaid.js.org/syntax/architecture
architecture-beta
group internet_zone(internet)[用戶端]
group app_zone(cloud)[應用層]
group data_zone(database)[資料層]
service browser(internet)[瀏覽器] in internet_zone
service lb(gateway)[負載均衡 Nginx] in app_zone
service api1(server)[API Server 1] in app_zone
service api2(server)[API Server 2] in app_zone
service db(database)[PostgreSQL] in data_zone
service cache(disk)[Redis 快取] in data_zone
browser:R --> L:lb
lb:R --> L:api1
lb:R --> L:api2
api1:B --> T:db
api1:B --> T:cache
api2:B --> T:db
api2:B --> T:cache
[標籤] 和服務標籤 [標籤] 均支援中文，直接寫即可group 用戶組(cloud)[用戶端] 中，用戶組 是 ID，不能用中文group clientZone(cloud)[用戶端]，標籤才是中文| 問題 | 原因 | 解法 |
|---|---|---|
| 環境不支援、圖表空白 | 需要 v11.0+ | 改用 flowchart LR + subgraph |
| service ID 用中文報錯 | ID 必須是英文 | service dbServer(database)[資料庫]，標籤才用中文 |
| 連線方向箭頭畫錯 | L/R/T/B 不直覺 | 先畫草圖確認方向，A:R --> L:B = 從 A 右側出發接到 B 左側 |
| icon 名稱不存在靜默失敗 | icon 拼錯 | 查官方 icon 清單，常見的就 server/database/cloud/internet |
最低版本：v11.4+ 平台相容性：極低（目前僅 mermaid-live-editor、Claude Artifacts 等最新環境支援）
⚠️ 使用前務必確認環境：Obsidian、GitHub、GitLab、VS Code 多數尚不支援。若需要廣泛相容，請改用
flowchart TD模擬看板版面。
kanban
column1[<欄位標題>]
task1[<任務名稱>]
task2[<任務名稱>]@{ ticket: "ISSUE-123", priority: "高" }
column2[<欄位標題>]
task3[<任務名稱>]
@{ } 屬性）| 屬性 | 說明 | 範例 |
|---|---|---|
ticket | Issue/Ticket 編號 | ticket: "JIRA-42" |
priority | 優先級（顯示標籤） | priority: "Very High" |
assigned | 負責人 | assigned: "小明" |
kanban
todo[待辦事項]
task1["修復登入頁面 CSS"]@{ ticket: "FE-101", priority: "High" }
task2["撰寫 API 文件"]@{ ticket: "BE-55" }
task3["評估第三方支付方案"]
inProgress[進行中]
task4["重構購物車邏輯"]@{ ticket: "BE-48", assigned: "小王", priority: "Very High" }
task5["設計通知中心 UI"]@{ ticket: "FE-89", assigned: "小李" }
review[審查中]
task6["訂單列表效能優化"]@{ ticket: "BE-61", assigned: "小張" }
done[已完成]
task7["用戶頭像上傳功能"]@{ ticket: "FE-77" }
task8["修復日期格式 Bug"]@{ ticket: "BE-59" }
[標籤] 和任務名稱 [標籤] 均支援中文task1["修復問題(緊急)"]assigned: "小明"| 問題 | 原因 | 解法 |
|---|---|---|
| 整個圖表不顯示 | 環境版本 < v11.4 | 確認環境版本，或改用 flowchart TD 模擬 |
@{ } metadata 不顯示 | 環境不支援 / 語法錯誤 | 簡化為無 metadata 版本先測試 |
| 任務名含特殊符號報錯 | 同 flowchart 規則 | 整個名稱加雙引號 |
ticket 號碼含 - 報錯 | 需要加引號 | ticket: "JIRA-42"（有引號才安全） |
flowchart LR
subgraph 待辦
T1["修復登入頁面 CSS
(FE-101 高優先)"]
T2[撰寫 API 文件]
end
subgraph 進行中
T3["重構購物車邏輯
(BE-48 非常高)"]
end
subgraph 審查中
T4[訂單列表效能優化]
end
subgraph 已完成
T5[用戶頭像上傳功能]
end
使用 mermaid code block（三個反引號 + mermaid）
HTML artifact 範本：
<!DOCTYPE html>
<html lang="zh-TW">
<head>
<meta charset="UTF-8">
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
mermaid.initialize({
startOnLoad: true,
theme: 'default',
themeVariables: {
fontFamily: '"Noto Sans TC", "Microsoft JhengHei", "PingFang TC", sans-serif'
}
});
</script>
</head>
<body>
<pre class="mermaid">
<!-- 圖表程式碼放這裡 -->
</pre>
</body>
</html>
更多 React artifact 範本見 references/react-template.md
| 錯誤現象 | 原因 | 解法 |
|---|---|---|
| 節點不顯示 | 中文含括號 | 用雙引號包裹整個標籤 |
| Parse error | 特殊符號衝突 | 將標籤加雙引號 |
| ER 圖欄位報錯 | 欄位名含中文 | 改用英文欄位名，用 comment 加中文 |
| 序列圖亂碼 | 編碼問題 | 確保檔案為 UTF-8 |
| Class 方法錯誤 | 中文方法名 | 改用英文方法名 |
| Gitgraph branch 錯誤 | 中文 branch 名 | 改用英文 branch 名 |
| 中文顯示方塊 | 缺乏字型 | 設定 themeVariables.fontFamily |
mermaid.initialize({
theme: 'default', // default | dark | forest | base | neutral
themeVariables: {
fontFamily: '"Noto Sans TC", "Microsoft JhengHei", sans-serif'
}
});
以下議題來自 GitHub Issues、Obsidian Forum、Stack Overflow、DEV Community 等論壇的實際回報，屬於官方文件未明確說明的隱藏地雷。
AND / OR 在邊標籤中是保留關鍵字論壇來源：技術部落格 CSMAIR、GitHub mermaid-js（多個 issue）
現象：即使用引號包裹，在邊標籤（edge label）中使用 AND 或 OR 仍可能導致 Parse error。
# 危險：AND / OR 在邊標籤會觸發 parser 邏輯運算子解析
flowchart LR
Tester -->|"q=[cond1, AND, cond2]"| API ← 可能報錯
# 安全：用底線包裹或換用符號
flowchart LR
Tester -->|"q=[cond1, _AND_, cond2]"| API ← 安全
Tester -->|"q=cond1 + cond2"| API ← 安全（AND 語義用 +）
Tester -->|"q=cond1 / cond2"| API ← 安全（OR 語義用 /）
根本原因：Mermaid 的內部 parser 把 AND/OR 當作邏輯運算子 token，在某些 rendering context 下就算有引號也無法完全隔離。
規則：邊標籤中避免使用純大寫的 AND、OR；需要時用 _AND_、+、或中文「且」「或」替代。
<...> 被 HTML renderer 解析為 HTML tag論壇來源：CSMAIR 技術部落格（Dec 2025）、GitHub mermaid-js #5498
現象：在 HTML-based 渲染器（VS Code Markdown PDF、Obsidian、GitHub Pages 等）中，角括號內純英文的內容會被解析為 HTML tag，導致 Parse error。
# 危險：純英文角括號 → 被誤解為 HTML tag
A -.->|"200(rows=<row>)"| T ← 誤解為 <row> tag，報錯
A -.->|"200(rows=<unchanged>)"| T ← 誤解為 <unchanged> tag，報錯
# 特別危險：真正的 HTML tag 名稱（即使加了其他字元仍失敗）
A -.->|"200(rows=<meta값유지>)"| T ← 仍失敗！<meta 被識別為 HTML meta tag
# 安全：加入非英文字元或數字打破 HTML tag 模式
A -.->|"200(rows=<1row>)"| T ← 安全（有數字）
A -.->|"200(rows=<資料列>)"| T ← 安全（有中文）
A -.->|"200(rows=<row_數量>)"| T ← 安全（有底線+中文）
危險 HTML tag 名稱黑名單（加中文字元仍失敗）：
<meta>, <div>, <span>, <a>, <p>, <br>, <script>, <style>, <input>, <form>, <head>, <body>, <html>
規則：邊標籤或節點標籤中若含角括號，要麼改用中文字元取代英文，要麼用 #60;（<）和 #62;（>）逸出碼。
# 最安全：用逸出碼
A -->|"狀態: #60;active#62;"| B
linkStyle 中 hex 色碼放最後一個屬性會報錯論壇來源：GitHub mermaid-js #5498（May 2024，狀態：Open）
現象：# 開頭的 hex 色碼如果是 linkStyle 屬性的最後一個，會被 parser 當作 Mermaid entity code（如 #35;）觸發 Parse error。
# 危險：hex 色碼在最後一個屬性位置
linkStyle 0 stroke-width:4px,stroke:#FF69B4 ← Parse error！
linkStyle 0 color:red,stroke:#FF69B4 ← Parse error！
# 安全方法 1：確保 hex 色碼不在最後（後面再接其他屬性）
linkStyle 0 stroke:#FF69B4,stroke-width:4px ← 安全（hex 不在最後）
# 安全方法 2：用 CSS 具名色取代 hex（適合常用色）
linkStyle 0 stroke-width:4px,stroke:HotPink ← 安全
linkStyle 0 stroke-width:4px,stroke:deepskyblue ← 安全
# 安全方法 3：在 hex 色碼後加分號結尾
linkStyle 0 stroke-width:4px,stroke:#FF69B4; ← 某些版本可用
根本原因：Mermaid parser 的 # 符號處理邏輯在行尾位置有 bug，會誤當 entity code 處理。此 bug 在 v10.9.0、v11.x 均存在（截至 2025 仍 Open）。
最佳實踐：linkStyle 時永遠把 hex 色碼排在第一個屬性，或改用 CSS 具名色。
direction 指令在多數情況下無效論壇來源：GitHub mermaid-js #2509, #3096, #4648, #4738, #6427, #6438（均為 Open/持續回報）
現象：在 subgraph 內設定 direction 指令，實際上不起作用或行為不一致，這是一個長期存在的已知 bug。
# 以下寫法語法正確但 direction 實際上常被忽略：
flowchart TD
subgraph 群組A
direction LR ← 看起來合法，實際上常無效
A --> B
end
subgraph 群組B
direction TB ← 同上，常被忽略
C --> D
end
已知觸發條件：
TD 且子圖也設 direction TD，某些版本直接報 Parse error（#6427）規則與替代方案：
# 替代方案 1：不在 subgraph 內用 direction，接受外層方向
flowchart LR
subgraph 群組A
A --> B
end
# 替代方案 2：改用多個獨立圖表表達不同方向
# 替代方案 3：改用 Architecture 圖（v11+，原生支援混合方向）
architecture-beta
group groupA(cloud)[群組A]
service a(server)[A] in groupA
service b(server)[B] in groupA
警告：不要在文件中記錄「subgraph direction 可以設定子圖方向」，會誤導讀者。此功能的 Issues 從 2021 到 2025 持續未修復。
論壇來源：Obsidian Forum 多篇（2023–2025）、GitHub Mermaid-Chart/vscode-mermaid-preview #145
現象：在某個平台測試成功的圖表，換到另一個平台出現 "No diagram type detected" 錯誤。
各平台 Mermaid 版本落後情況（2025 年觀察）：
| 平台/工具 | 已知問題 | 說明 |
|---|---|---|
| Obsidian | 常落後 2–3 個大版本 | timeline、block、packet、kanban、architecture 等新圖表常不支援 |
| VS Code 原生 Markdown Preview | 版本固定於 VS Code 發布時 | 需安裝第三方 extension 才能使用新語法 |
| GitHub | 更新較及時 | 通常支援到 v10+ |
| GitLab | 中等速度更新 | 偶有落後 |
| Notion | 整合版本較舊 | 只支援基本圖表 |
| Claude.ai Artifacts | 透過 CDN 載入，可指定版本 | 指定 @11 可用最新功能 |
各圖表類型最低版本需求：
| 圖表類型 | 引入版本 | Obsidian 常見狀態 |
|---|---|---|
| flowchart / sequenceDiagram | v0.x | 穩定支援 |
| classDiagram | v8.x | 穩定支援 |
| stateDiagram-v2 | v8.x | 穩定支援 |
| mindmap | v9.4+ | 部分版本不支援 |
| timeline | v9.4+ | 常不支援 |
| gitgraph | v9.0+ | 大多支援 |
| xychart-beta | v10.3+ | 較少平台支援 |
| block | v11.0+ | 多數平台不支援 |
| architecture-beta | v11.0+ | 多數平台不支援 |
| kanban | v11.4+ | 極少平台支援 |
| packet-beta | v11.0+ | 多數平台不支援 |
| radar | v11.4+ | 極少平台支援 |
規則：
https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs---）與 %%{init:...}%% 指令的版本與平台相容性論壇來源：Obsidian Forum #51541、GitHub mermaid-js 多個 issues
兩種設定方式的差異：
| 特性 | Front Matter（---） | %%{init:...}%% 指令 |
|---|---|---|
| 引入版本 | v10.0+ | v8.x+ |
| 語法 | YAML 格式 | JSON-like 格式 |
| 平台相容性 | 較差（v10+ 才支援） | 較佳（v8 起廣泛支援） |
| 功能 | title + config | config only |
Front Matter 正確語法（v10+）：
***
title: 我的流程圖
config:
theme: base
flowchart:
htmlLabels: false
themeVariables:
primaryColor: "#e8f4f8"
***
flowchart TD
A --> B
%%{init}%% 指令正確語法（v8+ 廣泛相容）：
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#e8f4f8'}}}%%
flowchart TD
A --> B
常見錯誤：
# 錯誤：Front Matter 縮排用 Tab（YAML 不允許 Tab）
***
config:
theme: base ← 這裡其實是 Tab 縮排，會報錯，必須用空格
***
# 錯誤：Obsidian 舊版不支援 Front Matter，用了等於圖表整個不渲染
***
title: 測試
***
classDiagram ← Obsidian 舊版報 Parse error on line 1
# 錯誤：%%{init}%% 使用單引號以外的引號格式
%%{init: {"theme": "base"}}%% ← 某些平台不接受雙引號，用單引號更穩
%%{init: {'theme': 'base'}}%% ← 建議格式
# 正確：不確定平台版本時，theme 用 %%{init}%%，不用 Front Matter
%%{init: {'theme': 'forest'}}%%
flowchart LR
A --> B
規則：
%%{init:...}%%，不用 Front MatterdateFormat 與 axisFormat 差異、以及任務數量上限論壇來源：GitHub mermaid-js-cli #784、GitHub mermaid-live-editor discussion #1386
dateFormat vs axisFormat 的常見混淆：
| 指令 | 作用 | 預設值 |
|---|---|---|
dateFormat | 輸入格式：你在程式碼裡寫的日期格式 | YYYY-MM-DD |
axisFormat | 輸出格式：X 軸顯示的日期格式 | YYYY-MM-DD |
# 常見誤解：設了 dateFormat 以為軸上顯示也會改 → 不會！
gantt
dateFormat DD-MM-YYYY ← 輸入格式改為 DD-MM-YYYY
title 甘特圖
section 階段一
任務A: 01-01-2025, 30d ← 輸入要符合 dateFormat
# 要改軸上顯示，需要另外設 axisFormat
gantt
dateFormat YYYY-MM-DD
axisFormat %m/%d ← 顯示格式改為月/日
title 甘特圖
section 階段一
任務A: 2025-01-01, 30d
任務數量靜默失敗問題：
# Bug：gantt 任務超過約 15 個時，可能靜默失敗（不報錯但不渲染）
gantt
dateFormat YYYY-MM-DD
section 階段
任務1: 2024-01-01, 7d
任務2: after 任務1, 7d
... （超過 ~15 個任務）
任務16: after 任務15, 7d ← 可能完全不顯示，且無錯誤訊息
解法：超過 10 個任務時，考慮拆分成多個 gantt 圖，或改用 timeline 圖表。
axisFormat 常用格式碼（基於 moment.js）：
| 格式碼 | 輸出範例 | 說明 |
|---|---|---|
%Y-%m-%d | 2025-01-15 | 完整日期 |
%m/%d | 01/15 | 月/日 |
%b %d | Jan 15 | 英文月縮寫 |
%Y-Q%q | 2025-Q1 | 年-季度（v10+） |
%W週 | 03週 | 第幾週 |
更多細節見 references/ 目錄：
在使用者要設計網站、Web App 或元件介面時使用。常見觸發像「做 landing page」「設計 dashboard」「規劃 component UI」。輸出可上線介面與設計系統；不取代產品策略或純品牌研究。
在使用者要把模糊想法整理成可開發 spec 時使用。常見觸發像「整理需求成 spec」「補驗收條件」「拆分階段開發計畫」。輸出技術規格、白話規格與可直接貼用於 Codex / Claude Code 的分階段 instructions；不直接代替正式文件發布。
在非程式開發者要用 vibe coding 與 coding agent 協作時使用。常見觸發像「幫我整理開發準則」「定義交付邊界」「規劃驗證方式」。輸出需求表達、邊界與風險控管準則；不直接取代實作。
當使用者要拆解大型、混亂、跨部門、反覆卡關或高不確定性的難題，或明確要求做問題拆解、issue tree、根因與對策分層時使用。先分清楚現象、目標落差、真正問題與根因假設，再判斷問題是範疇型、分析型、動態系統型、研究型或交付型，最後用 issue tree/MECE、WBS、系統思考、驗收標準、依賴排程、資源分派與流動指標，產出可執行的問題拆解報告、工作包、關鍵路徑、並行策略與 PDCA 回饋節奏。
當使用者要替代解法、不同思路、更簡單或更穩定做法時使用。將現有方案重構成結構問題，提出多條可落地方案與最低摩擦解。
建立定期任務（每日晨報、每週回顧）。當使用者需要設定自動化的、定期執行的任務時使用。