pretty-mermaid

Pretty Mermaid

使用單一指令即可渲染出精美且專業風格的 Mermaid 圖表。支援 SVG（適用於網頁/文件）與 ASCII（適用於終端機）。

快速開始

渲染單一圖表

從檔案渲染：

node scripts/render.mjs \
  --input diagram.mmd \
  --output diagram.svg \
  --format svg \
  --theme tokyo-night

從使用者提供的 Mermaid 程式碼渲染：

1. 將程式碼儲存為 .mmd 檔案
2. 使用所需主題執行渲染腳本

批次渲染多個圖表

node scripts/batch.mjs \
  --input-dir ./diagrams \
  --output-dir ./output \
  --format svg \
  --theme dracula \
  --workers 4

ASCII 輸出（終端機友善）

node scripts/render.mjs \
  --input diagram.mmd \
  --format ascii \
  --use-ascii

---

工作流程決策樹

步驟 1：使用者想要什麼？

• 渲染現有的 Mermaid 程式碼 → 前往 渲染圖表
• 建立新圖表 → 前往 建立圖表
• 套用/變更主題 → 前往 主題
• 批次處理 → 前往 批次渲染

步驟 2：選擇輸出格式

• SVG（網頁、文件、簡報）→ --format svg
• ASCII（終端機、日誌、純文字）→ --format ascii

步驟 3：選擇主題

• 深色模式文件 → tokyo-night（推薦）
• 淺色模式文件 → github-light
• 鮮豔色彩 → dracula
• 查看所有主題 → 執行 node scripts/themes.mjs

---

渲染圖表

從檔案渲染

當使用者提供 .mmd 檔案或 Mermaid 程式碼區塊時：

1. 儲存為檔案（如果是程式碼區塊）：

   cat > diagram.mmd << 'EOF'
   flowchart LR
       A[Start] --> B[End]
   EOF
   

2. 使用主題渲染：

   node scripts/render.mjs \
     --input diagram.mmd \
     --output diagram.svg \
     --theme tokyo-night
   

3. 驗證輸出：

   • SVG：在瀏覽器中開啟或嵌入文件
   • ASCII：在終端機中顯示

輸出格式

SVG（可縮放向量圖形）

• 最佳用途：網頁、文件、簡報
• 特色：完整色彩支援、透明背景、可縮放
• 用法：--format svg --output diagram.svg

ASCII（終端機圖形）

• 最佳用途：終端機輸出、純文字日誌、README 檔案
• 特色：純文字、隨處可用、無需依賴
• 用法：--format ascii（輸出到標準輸出）
• 選項：
  • --use-ascii - 使用純 ASCII（無 Unicode）
  • --padding-x 5 - 水平間距
  • --padding-y 5 - 垂直間距

進階選項

自訂顏色（覆蓋主題）：

node scripts/render.mjs \
  --input diagram.mmd \
  --bg "#1a1b26" \
  --fg "#a9b1d6" \
  --accent "#7aa2f7" \
  --output custom.svg

透明背景：

node scripts/render.mjs \
  --input diagram.mmd \
  --transparent \
  --output transparent.svg

自訂字型：

node scripts/render.mjs \
  --input diagram.mmd \
  --font "JetBrains Mono" \
  --output custom-font.svg

---

建立圖表

使用範本

步驟 1：列出可用範本

ls assets/example_diagrams/
# flowchart.mmd  sequence.mmd  state.mmd  class.mmd  er.mmd

步驟 2：複製並修改

cp assets/example_diagrams/flowchart.mmd my-workflow.mmd
# 根據使用者需求編輯 my-workflow.mmd

步驟 3：渲染

node scripts/render.mjs \
  --input my-workflow.mmd \
  --output my-workflow.svg \
  --theme github-dark

圖表類型參考

詳細語法與最佳實務請參閱 DIAGRAM_TYPES.md。

快速參考：

流程圖 - 流程、工作流程、決策樹

flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]

序列圖 - API 呼叫、互動、訊息流程

sequenceDiagram
    User->>Server: Request
    Server-->>User: Response

狀態圖 - 應用程式狀態、生命週期、有限狀態機

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading
    Loading --> [*]

類別圖 - 物件模型、架構、關係

classDiagram
    User --> Post: creates
    Post --> Comment: has

ER 圖 - 資料庫結構、資料模型

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains

根據使用者需求建立

步驟 1：識別圖表類型

• 流程/工作流程 → 流程圖
• API/互動 → 序列圖
• 狀態/生命週期 → 狀態圖
• 物件模型 → 類別圖
• 資料庫 → ER 圖

步驟 2：建立圖表檔案

cat > user-diagram.mmd << 'EOF'
# [插入產生的 Mermaid 程式碼]
EOF

步驟 3：渲染並迭代

node scripts/render.mjs \
  --input user-diagram.mmd \
  --output preview.svg \
  --theme tokyo-night

# 與使用者檢視，必要時編輯 diagram.mmd，重新渲染

---

主題

列出可用主題

node scripts/themes.mjs

輸出：

Available Beautiful-Mermaid Themes:

 1. zinc-light
 2. zinc-dark
 3. tokyo-night
 4. tokyo-night-storm
 5. tokyo-night-light
 6. catppuccin-mocha
 7. catppuccin-latte
 8. nord
 9. nord-light
10. dracula
11. github-dark
12. github-light
13. solarized-dark
14. solarized-light
15. one-dark

Total: 15 themes

主題選擇指南

適用於深色模式文件：

• tokyo-night ⭐ - 現代、開發者友善
• github-dark - 熟悉的 GitHub 風格
• dracula - 鮮豔、高對比
• nord - 冷色調、極簡

適用於淺色模式文件：

• github-light - 乾淨、專業
• zinc-light - 高對比、適合列印
• catppuccin-latte - 溫暖、友善

詳細主題資訊： 請參閱 THEMES.md

將主題套用至圖表

node scripts/render.mjs \
  --input diagram.mmd \
  --output themed.svg \
  --theme tokyo-night

比較主題

使用多個主題渲染同一圖表：

for theme in tokyo-night dracula github-dark; do
  node scripts/render.mjs \
    --input diagram.mmd \
    --output "diagram-${theme}.svg" \
    --theme "$theme"
done

---

批次渲染

批次渲染目錄

步驟 1：整理圖表

diagrams/
├── architecture.mmd
├── workflow.mmd
└── database.mmd

步驟 2：批次渲染

node scripts/batch.mjs \
  --input-dir ./diagrams \
  --output-dir ./rendered \
  --format svg \
  --theme tokyo-night \
  --workers 4

輸出：

Found 3 diagram(s) to render...
✓ architecture.mmd
✓ workflow.mmd
✓ database.mmd

3/3 diagrams rendered successfully

批次處理多種格式

同時渲染 SVG 與 ASCII：

# SVG 用於文件
node scripts/batch.mjs \
  --input-dir ./diagrams \
  --output-dir ./svg \
  --format svg \
  --theme github-dark

# ASCII 用於 README
node scripts/batch.mjs \
  --input-dir ./diagrams \
  --output-dir ./ascii \
  --format ascii \
  --use-ascii

效能選項

• --workers N - 平行渲染（預設：4）
• 建議：10 個以上圖表使用 --workers 8

---

常見使用案例

1. 文件用的架構圖

# 使用者提供架構描述
# → 建立 flowchart.mmd
# → 使用專業主題渲染

node scripts/render.mjs \
  --input architecture.mmd \
  --output docs/architecture.svg \
  --theme github-dark \
  --transparent

2. API 序列圖

# 使用者描述 API 流程
# → 建立 sequence.mmd
# → 使用清晰主題渲染

node scripts/render.mjs \
  --input api-flow.mmd \
  --output api-sequence.svg \
  --theme tokyo-night

3. 資料庫結構視覺化

# 使用者提供資料表定義
# → 建立 er.mmd
# → 渲染為資料庫文件

node scripts/render.mjs \
  --input schema.mmd \
  --output database-schema.svg \
  --theme dracula

4. 終端機友善的工作流程

# 用於 README 或終端機顯示
node scripts/render.mjs \
  --input workflow.mmd \
  --format ascii \
  --use-ascii > workflow.txt

5. 簡報投影片

# 高對比適合投影機
node scripts/render.mjs \
  --input slides-diagram.mmd \
  --output presentation.svg \
  --theme zinc-light

---

疑難排解

beautiful-mermaid 未安裝

Error: Cannot find module 'beautiful-mermaid'

注意： 首次執行時應自動安裝。若失敗：

cd /path/to/pretty-mermaid-skill && npm install

Mermaid 語法無效

Error: Parse error on line 3

解決方法：

1. 對照 DIAGRAM_TYPES.md 驗證語法
2. 在 https://mermaid.live/ 上測試
3. 檢查常見錯誤：
   • A --> B 中缺少空格
   • 節點形狀語法錯誤
   • 未閉合的括號

找不到檔案

Error: Input file not found: diagram.mmd

解決方法： 確認檔案路徑正確，必要時使用絕對路徑

---

資源

scripts/

可執行的 Node.js 腳本，用於渲染操作：

• render.mjs - 主要渲染腳本
• batch.mjs - 批次處理腳本
• themes.mjs - 主題列表工具

references/

用於建立圖表的文件：

• THEMES.md - 詳細主題參考與範例
• DIAGRAM_TYPES.md - 所有圖表類型的完整語法指南
• api_reference.md - beautiful-mermaid API 文件

assets/

快速建立圖表的範本檔案：

• example_diagrams/flowchart.mmd - 流程圖範本
• example_diagrams/sequence.mmd - 序列圖範本
• example_diagrams/state.mmd - 狀態圖範本
• example_diagrams/class.mmd - 類別圖範本
• example_diagrams/er.mmd - ER 圖範本

---

提示與最佳實務

效能

• 3 個以上圖表使用批次渲染（平行處理）
• 圖表節點數維持在 50 個以下以確保快速渲染
• 使用 ASCII 進行快速預覽

品質

• 技術文件使用 tokyo-night 或 github-dark
• 為深色/淺色模式相容性加入透明度：--transparent
• 在批次渲染前先在目標環境中測試主題

工作流程

1. 從 assets/example_diagrams/ 的範本開始
2. 根據使用者回饋迭代
3. 最後再套用主題
4. 如有需要，同時渲染 SVG（文件）與 ASCII（README）

無障礙性

• 簡報使用高對比主題
• 為所有連線加上文字標籤
• 避免僅以顏色編碼資訊