md2draw: Markdown to Excalidraw

將 Markdown 的想法和計劃, 一鍵轉換成有質感的 Excalidraw 圖表.

特色

• AI 解析: 由 Claude Code 直接分析文件結構與關係, 不需另外呼叫 API
• 手繪風格: Excalidraw 原生字體和粗糙感
• 自動排版: 依內容語意自動選擇 tree、mindmap、timeline、flowchart 等版面
• 層次顏色: 不同深度的節點用不同顏色區分
• 智能連線: 自動識別文中的關聯關係

安裝

1. 將 md2draw.md 放到 ~/.claude/commands/

   converter.js 需要放在固定位置, 並在 md2draw.md 裡指定正確路徑.

   ~/.claude/
   ├── commands/
   │   └── md2draw.md          ← slash command 定義
   └── scripts/
       └── md2excalidraw/
           └── converter.js    ← 主程式
   

   ~/.claude/commands/ 是全域設定, 對所有專案都生效. 若只想在特定專案使用, 改放 .claude/commands/md2draw.md（專案根目錄下）即可.

2. API Key（選用）

   透過 /md2draw 執行時, 結構分析由 Claude Code 自己完成, 不需要設定 API Key. 只有在不透過 Claude Code、單獨執行 converter.js（不帶 --diagram-json 旗標）時, 才需要設定環境變數 ANTHROPIC_API_KEY.

使用方式

/md2draw docs/my-idea.md
/md2draw docs/api-flow.md --layout sequence --font cascadia --style dark

參數說明

--style 主題風格

值	效果
sketch	淺色背景, 手繪粗糙感（預設）
dark	深色背景（#0f172a）, 高對比配色

--layout 圖表語意類型

描述的是內容的性質, 不是視覺方向. 預設 auto, 由 Claude 根據 Markdown 自動判斷.

值	最適合	典型內容
auto	讓 AI 決定（預設）	任何內容
tree	層次結構、組織圖	深度 heading 巢狀
mindmap	一個中心概念向外發散	腦力激盪、概念圖
timeline	有序的階段、里程碑	Q1/Q2 計劃、發布時程
flowchart	步驟流程、決策分支	SOP、if/then 邏輯
comparison	並排比較、優缺點	工具評估、Persona
architecture	系統設計、模組分組	技術架構、服務圖
kanban	任務依狀態分欄	todo/doing/done、Sprint
sequence	角色之間的訊息交換	API 流程、認證握手、UML

--font 字體

值	Excalidraw 字體	風格
virgil	Virgil	手繪感, 輕鬆自然（預設）
helvetica	Helvetica	乾淨無襯線, 正式簡潔
cascadia	Cascadia Code	等寬字體, 工程/程式碼感

開啟生成的 .excalidraw 檔案

工具	方式
Excalidraw.com	直接拖拽 .excalidraw 到網頁
VSCode	安裝 Excalidraw 插件（by pomdtr）
Obsidian	安裝 Excalidraw 插件（by Zsolt Viczian）

技術架構

Markdown 檔案
    ↓
結構分析
    ├── 預設: Claude Code 自己分析, 不另外呼叫 API
    └── 單獨執行 converter.js 時: 改由 analyzeWithClaude() 呼叫 Anthropic API
    ↓ 結構化 JSON
    ├── 一般 layout: { nodes, connections, layoutType }
    └── sequence: { actors, messages, groups }
    ↓
Layout Engine（根據語意類型計算座標）
    ├── tree / mindmap / timeline / flowchart
    ├── comparison / architecture / kanban
    └── sequence（獨立引擎: lifeline、message arrow）
    ↓
Excalidraw JSON Builder
    ├── rectangle + text（節點）
    ├── arrow（連線、hierarchy、語意連結）
    ├── line（timeline rail、sequence lifeline）
    └── diamond（flowchart 決策點）
    ↓
.excalidraw 檔案（Excalidraw v2 格式）

converter.js 接受 --diagram-json=<path> 旗標: 有給就直接讀那份 JSON, 跳過 analyzeWithClaude(). 透過 /md2draw 執行時, Claude Code 會先自己產生結構 JSON 寫到暫存檔, 再帶這個旗標呼叫 converter.js, 預設流程因此不需要 Anthropic API Key; 只有沒帶 --diagram-json（單獨執行 converter.js 的場景）才會呼叫 analyzeWithClaude().

Sequence Diagram

Sequence layout 採用完全獨立的資料結構和 builder:

• actors: 頂部、底部 actor 方框, 中間虛線 lifeline
• messages: 水平箭頭, 依 type 自動選擇線條樣式:
  • sync: 實線, 實心箭頭（預設呼叫）
  • async: 實線, 開放箭頭（fire-and-forget）
  • return: 虛線, 開放箭頭（回應）
  • create: 實線, 綠色（建立新 actor）
  • destroy: 虛線, 紅色（銷毀 actor）
• groups: loop / alt / opt 框住指定訊息範圍
• self-call: elbow arrow（右彎迴圈）

License

MIT