Excalidraw Diagram

Excalidraw Diagram Generator

Create Excalidraw diagrams from text content with multiple output formats.

Output Modes

根據使用者的觸發詞選擇輸出模式：

Workflow

1. Detect output mode from trigger words (see Output Modes table above)
2. Analyze content - identify concepts, relationships, hierarchy
3. Choose diagram type (see Diagram Types below)
4. Generate Excalidraw JSON (add animation order if Animated mode)
5. Output in correct format based on mode
6. Automatically save to current working directory
7. Notify user with file path and usage instructions

Output Formats

Mode 1: Obsidian Format (Default)

嚴格按照以下結構輸出，不得有任何修改：

---
excalidraw-plugin: parsed
tags: [excalidraw]
---
==⚠  Switch to EXCALIDRAW VIEW in the MORE OPTIONS menu of this document. ⚠== You can decompress Drawing data with the command palette: 'Decompress current Excalidraw file'. For more info check in plugin settings under 'Saving'

# Excalidraw Data

## Text Elements
%%
## Drawing
```json
{JSON 完整資料}

%%

**關鍵要點：**
- Frontmatter 必須包含 `tags: [excalidraw]`
- 警告訊息必須完整
- JSON 必須被 `%%` 標記包圍
- 不能使用 `excalidraw-plugin: parsed` 以外的其他 frontmatter 設定
- **副檔名**：`.md`

### Mode 2: Standard Excalidraw Format

直接輸出純 JSON 檔案，可在 excalidraw.com 開啟：

```json
{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [...],
  "appState": {
    "gridSize": null,
    "viewBackgroundColor": "#ffffff"
  },
  "files": {}
}

關鍵要點：

• source 使用 https://excalidraw.com（不是 Obsidian 外掛）
• 純 JSON，無 Markdown 包裝
• 副檔名：.excalidraw

Mode 3: Animated Excalidraw Format

與 Standard 格式相同，但每個元素添加 customData.animate 欄位控制動畫順序：

{
  "id": "element-1",
  "type": "rectangle",
  "customData": {
    "animate": {
      "order": 1,
      "duration": 500
    }
  },
  ...其他標準欄位
}

動畫順序規則：

• order: 動畫播放順序（1, 2, 3...），數字越小越先出現
• duration: 該元素的繪製時長（毫秒），預設 500
• 相同 order 的元素同時出現
• 建議順序：標題 → 主要框架 → 連接線 → 細節文字

使用方法：

1. 產生 .excalidraw 檔案
2. 拖到 https://dai-shi.github.io/excalidraw-animate/
3. 點擊 Animate 預覽，然後匯出 SVG 或 WebM

副檔名：.excalidraw

Diagram Types & Selection Guide

選擇合適的圖表形式，以提升理解力與視覺吸引力。

Design Rules

Text & Format

• 所有文字元素必須使用 fontFamily: 5（Excalifont 手寫字型）
• 文字中的雙引號替換規則：" 替換為 『』
• 文字中的圓括號替換規則：() 替換為 「」
• 字型大小規則（硬性下限，低於此值在正常縮放下不可讀）：
  • 標題：20-28px（最小 20px）
  • 副標題：18-20px
  • 正文/標籤：16-18px（最小 16px）
  • 次要註釋：14px（僅限不重要的輔助說明，慎用）
  • 絕對禁止低於 14px
• 行高：所有文字使用 lineHeight: 1.25
• 文字置中估算：獨立文字元素沒有自動置中，需手動計算 x 座標：
  • 估算文字寬度：estimatedWidth = text.length * fontSize * 0.5（CJK 字元用 * 1.0）
  • 置中公式：x = centerX - estimatedWidth / 2
  • 範例：文字 "Hello"（5字元, fontSize 20）置中於 x=300 → estimatedWidth = 5 * 20 * 0.5 = 50 → x = 300 - 25 = 275

Layout & Design

• 畫布範圍：建議所有元素在 0-1200 x 0-800 區域內
• 最小形狀尺寸：帶文字的矩形/橢圓不小於 120x60px
• 元素間距：最小 20-30px 間距，防止重疊
• 層次清晰：使用不同顏色和形狀區分不同層級的資訊
• 圖形元素：適當使用矩形框、圓形、箭頭等元素來組織資訊
• 禁止 Emoji：不要在圖表文字中使用任何 Emoji 符號，如需視覺標記請使用簡單圖形（圓形、方形、箭頭）或顏色區分

Color Palette

文字顏色（strokeColor for text）：

形狀填充色（backgroundColor, fillStyle: "solid"）：

區域背景色（大矩形 + opacity: 30，用於分層圖表）：

對比度規則：

• 白底上文字最淺不低於 #757575，否則不可讀
• 淺色填充上用深色變體文字（如淺綠底用 #15803d，不用 #22c55e）
• 避免淺灰色文字（#b0b0b0、#999）出現在白底上

參考：references/excalidraw-schema.md

JSON Structure

Obsidian 模式：

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://github.com/zsviczian/obsidian-excalidraw-plugin",
  "elements": [...],
  "appState": { "gridSize": null, "viewBackgroundColor": "#ffffff" },
  "files": {}
}

Standard / Animated 模式：

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [...],
  "appState": { "gridSize": null, "viewBackgroundColor": "#ffffff" },
  "files": {}
}

Element Template

Each element requires these fields (do NOT add extra fields like frameId, index, versionNonce, rawText -- they may cause issues on excalidraw.com. boundElements must be null not [], updated must be 1 not timestamps):

{
  "id": "unique-id",
  "type": "rectangle",
  "x": 100, "y": 100,
  "width": 200, "height": 50,
  "angle": 0,
  "strokeColor": "#1e1e1e",
  "backgroundColor": "transparent",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 1,
  "opacity": 100,
  "groupIds": [],
  "roundness": {"type": 3},
  "seed": 123456789,
  "version": 1,
  "isDeleted": false,
  "boundElements": null,
  "updated": 1,
  "link": null,
  "locked": false
}

strokeStyle values: "solid"（實線，預設）| "dashed"（虛線）| "dotted"（點線）。虛線適合表示選擇性路徑、非同步流、弱關聯等。

Text elements add:

{
  "text": "顯示文字",
  "fontSize": 20,
  "fontFamily": 5,
  "textAlign": "center",
  "verticalAlign": "middle",
  "containerId": null,
  "originalText": "顯示文字",
  "autoResize": true,
  "lineHeight": 1.25
}

Animated 模式額外添加 customData 欄位：

{
  "id": "title-1",
  "type": "text",
  "customData": {
    "animate": {
      "order": 1,
      "duration": 500
    }
  },
  ...其他欄位
}

See references/excalidraw-schema.md for all element types.

Additional Technical Requirements

Text Elements 處理

• ## Text Elements 部分在 Markdown 中必須留空，僅用 %% 作為分隔符
• Obsidian ExcaliDraw 外掛會根據 JSON 資料自動填充文字元素
• 不需要手動列出所有文字內容

座標與佈局

• 座標系統：左上角為原點 (0,0)
• 建議範圍：所有元素在 0-1200 x 0-800 像素範圍內
• 元素 ID：每個元素需要唯一的 id（可以是字串，如「title」「box1」等）

Required Fields for All Elements

IMPORTANT: Do NOT include frameId, index, versionNonce, or rawText fields. Use boundElements: null (not []), and updated: 1 (not timestamps).

{
  "id": "unique-identifier",
  "type": "rectangle|text|arrow|ellipse|diamond",
  "x": 100, "y": 100,
  "width": 200, "height": 50,
  "angle": 0,
  "strokeColor": "#color-hex",
  "backgroundColor": "transparent|#color-hex",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid|dashed|dotted",
  "roughness": 1,
  "opacity": 100,
  "groupIds": [],
  "roundness": {"type": 3},
  "seed": 123456789,
  "version": 1,
  "isDeleted": false,
  "boundElements": null,
  "updated": 1,
  "link": null,
  "locked": false
}

Text-Specific Properties

文字元素 (type: "text") 需要額外屬性（do NOT include rawText）：

{
  "text": "顯示文字",
  "fontSize": 20,
  "fontFamily": 5,
  "textAlign": "center",
  "verticalAlign": "middle",
  "containerId": null,
  "originalText": "顯示文字",
  "autoResize": true,
  "lineHeight": 1.25
}

appState 配置

"appState": {
  "gridSize": null,
  "viewBackgroundColor": "#ffffff"
}

files 欄位

"files": {}

Common Mistakes to Avoid

• 文字偏移 — 獨立 text 元素的 x 是左邊緣，不是中心。必須用置中公式手動計算，否則文字會偏到一邊
• 元素重疊 — y 座標相近的元素容易堆疊。放置新元素前檢查與周圍元素是否有至少 20px 間距
• 畫布留白不足 — 內容不要貼著畫布邊緣。在四周留 50-80px 的 padding
• 標題沒有置中於圖表 — 標題應置中於下方圖表的整體寬度，不是固定在 x=0
• 箭頭標籤溢出 — 長文字標籤（如 "ATP + NADPH"）會超出短箭頭。保持標籤簡短或加大箭頭長度
• 對比度不夠 — 淺色文字在白底上幾乎不可見。文字顏色不低於 #757575，有色文字用深色變體
• 字級太小 — 低於 14px 在正常縮放下不可讀，正文最小 16px

Implementation Notes

Auto-save & File Generation Workflow

當產生 Excalidraw 圖表時，必須自動執行以下步驟：

1. 選擇合適的圖表類型

• 根據使用者提供的內容特性，參考上方 「Diagram Types & Selection Guide」 表
• 分析內容的核心訴求，選擇最合適的視覺化形式

2. 產生有意義的檔案名稱

根據輸出模式選擇副檔名：

• 優先使用中文以提高清晰度

3. 使用 Write 工具自動儲存檔案

• 儲存位置：目前工作目錄（自動偵測環境變數）
• 完整路徑：{current_directory}/[filename].md
• 這樣可以實現靈活遷移，無需寫死路徑

4. 確保 Markdown 結構完全正確

必須按以下格式產生（不能有任何修改）：

---
excalidraw-plugin: parsed
tags: [excalidraw]
---
==⚠  Switch to EXCALIDRAW VIEW in the MORE OPTIONS menu of this document. ⚠== You can decompress Drawing data with the command palette: 'Decompress current Excalidraw file'. For more info check in plugin settings under 'Saving'

# Excalidraw Data

## Text Elements
%%
## Drawing
```json
{完整的 JSON 資料}

%%

#### 5. JSON 資料要求
- 包含完整的 Excalidraw JSON 結構
- 所有文字元素使用 `fontFamily: 5`
- 文字中的 `"` 替換為 `『』`
- 文字中的 `()` 替換為 `「」`
- JSON 格式必須有效，通過語法檢查
- 所有元素有唯一的 `id`
- 包含 `appState` 和 `files: {}` 欄位

#### 6. 使用者回饋與確認
向使用者報告：
- 圖表已產生
- 精確的儲存位置
- 如何在 Obsidian 中檢視
- 圖表的設計選擇說明（選擇了什麼類型的圖表、為什麼）
- 是否需要調整或修改

### Example Output Messages

**Obsidian 模式：**

Excalidraw 圖已產生！

儲存位置：商業模式.relationship.md

使用方式：

1. 在 Obsidian 中開啟此檔案
2. 點擊右上角 MORE OPTIONS 選單
3. 選擇 Switch to EXCALIDRAW VIEW

**Standard 模式：**

Excalidraw 圖已產生！

儲存位置：商業模式.relationship.excalidraw

使用方式：

1. 開啟 https://excalidraw.com
2. 點擊左上角選單 → Open → 選擇此檔案
3. 或直接拖曳檔案到 excalidraw.com 頁面

**Animated 模式：**

Excalidraw 動畫圖已產生！

儲存位置：商業模式.relationship.animate.excalidraw

動畫順序：標題(1) → 主框架(2-4) → 連接線(5-7) → 說明文字(8-10)

產生動畫：

1. 開啟 https://dai-shi.github.io/excalidraw-animate/
2. 點擊 Load File 選擇此檔案
3. 預覽動畫效果
4. 點擊 Export 匯出 SVG 或 WebM