# 在VS Code使用Mermaid 圖表製作與匯出教學
> 🚀 **使用 VS Code 開發環境進行 Mermaid 圖表製作的完整指南**

## 📋 目錄
- [什麼是 Mermaid](#什麼是-mermaid)
- [VS Code 環境設置](#vs-code-環境設置)
- [基礎語法](#基礎語法)
- [流程圖範例](#流程圖範例)
- [在 VS Code 中開發](#在-vs-code-中開發)
- [在 HackMD 中使用](#在-hackmd-中使用)
- [本地環境匯出圖檔](#本地環境匯出圖檔)
- [進階技巧](#進階技巧)

---

## 什麼是 Mermaid

Mermaid 是一個基於 JavaScript 的圖表和流程圖生成工具，讓你可以用簡單的文字語法創建複雜的圖表。

### 🎯 主要優勢
- ✅ **語法簡單**：用文字就能描述複雜圖表
- ✅ **版本控制友善**：純文字格式，易於 Git 管理
- ✅ **多平台支援**：GitHub、GitLab、HackMD 等都支援
- ✅ **VS Code 完美整合**：豐富的擴展支援和即時預覽

---

## VS Code 環境設置

### 🔧 必裝擴展

在 VS Code 中安裝以下擴展，獲得最佳的 Mermaid 開發體驗：

#### 1. **Mermaid Markdown Syntax Highlighting**

擴展 ID: bpruitt-goddard.mermaid-markdown-syntax-highlighting

- ✅ 提供 Mermaid 語法高亮
- ✅ 支援即時預覽功能
- ✅ 錯誤檢查和語法提示

#### 2. **Markdown Preview Enhanced**

擴展 ID: shd101wyy.markdown-preview-enhanced

- ✅ 強化 Markdown 預覽
- ✅ 完美支援 Mermaid 圖表
- ✅ 匯出多種格式（PDF、HTML、PNG）

#### 3. **Mermaid Preview**

擴展 ID: vstirbu.vscode-mermaid-preview

- ✅ 專門的 Mermaid 預覽窗格
- ✅ 支援 `.mmd` 檔案格式
- ✅ 即時同步更新

### ⚙️ VS Code 設定

在 `settings.json` 中添加以下設定：

{
    "mermaid.theme": "neutral",
    "markdown-preview-enhanced.mermaidTheme": "neutral",
    "markdown-preview-enhanced.codeBlockTheme": "github.css",
    "files.associations": {
        "*.mmd": "mermaid"
    }
}

---

## 基礎語法

### 流程圖 (Flowchart)

flowchart TD
    A[開始] --> B{是否登入?}
    B -->|是| C[顯示主頁]
    B -->|否| D[跳轉登入頁]
    C --> E[結束]
    D --> E

### 時序圖 (Sequence Diagram)

sequenceDiagram
    participant A as 客戶端
    participant B as 伺服器
    participant C as 資料庫
    
    A->>B: 發送請求
    B->>C: 查詢資料
    C-->>B: 回傳結果
    B-->>A: 回應資料

### 類別圖 (Class Diagram)

classDiagram
    class User {
        +String name
        +String email
        +login()
        +logout()
    }
    
    class Admin {
        +String role
        +manageUsers()
    }
    
    User <|-- Admin

---

## 流程圖範例：出差費用申請系統

這是一個實際的企業系統架構圖：

flowchart TB
  HR[人力資源處]:::user
  PR[公關部]:::user2

  TRAVEL_WEB[出差費用申請系統]:::sys1
  ESG_WEB[ESG WEB]:::sys2

  ORACLE[Oracle<br>出差費用DB<br>（View 供查詢）]:::db

  %% 人力資源處操作出差系統
  HR --> TRAVEL_WEB
  %% 公關部操作 ESG WEB
  PR --> ESG_WEB

  %% 前端直接查詢 Oracle
  TRAVEL_WEB -- 讀寫/異動 --> ORACLE
  ESG_WEB -- 唯讀查詢 View --> ORACLE

  classDef user fill:#f9f9e8,stroke:#ffd700,stroke-width:1.5px;
  classDef user2 fill:#f6f8fc,stroke:#99b3e6,stroke-width:1.5px;
  classDef sys1 fill:#e8f3ff,stroke:#49a8ff,stroke-width:2px;
  classDef sys2 fill:#e9faec,stroke:#4ad991,stroke-width:2px;
  classDef db fill:#f3f3fb,stroke:#bc6aff,stroke-width:2px;

### 🎨 樣式說明
- **用戶角色**：黃色邊框，代表不同部門
- **系統應用**：藍色和綠色，區分不同系統
- **資料庫**：紫色邊框，表示資料存儲

---

## 在 VS Code 中開發

### 🎨 VS Code 開發流程

#### 1. **創建 Mermaid 檔案**

# 在 VS Code 中創建新檔案
新檔案 → 儲存為 diagram.mmd 或 diagram.md

#### 2. **即時預覽**
- **方法一**：`Ctrl+Shift+P` → 搜尋 "Mermaid: Preview"
- **方法二**：在 `.md` 檔案中按 `Ctrl+Shift+V` 預覽 Markdown
- **方法三**：右鍵點選檔案 → "Open Preview"

#### 3. **語法高亮與提示**
VS Code 會自動提供：
- 🎯 語法高亮顯示
- 🔍 錯誤檢查
- 💡 自動完成建議
- 📝 即時語法驗證

#### 4. **多窗格編輯**

編輯窗格 | 預覽窗格
---------|----------
程式碼   | 即時圖表
修改     | 自動更新

### 🚀 VS Code 快捷鍵

| 功能 | Windows/Linux | macOS |
|------|---------------|-------|
| 預覽 Markdown | `Ctrl+Shift+V` | `Cmd+Shift+V` |
| 開啟預覽到側邊 | `Ctrl+K V` | `Cmd+K V` |
| 命令面板 | `Ctrl+Shift+P` | `Cmd+Shift+P` |
| 格式化文檔 | `Shift+Alt+F` | `Shift+Option+F` |

### 💡 VS Code 實用技巧

#### 程式碼片段 (Snippets)
在 VS Code 中設定自訂程式碼片段：

{
    "Mermaid Flowchart": {
        "prefix": "mermaid-flow",
        "body": [
            "```mermaid",
            "flowchart TD",
            "    A[${1:開始}] --> B[${2:結束}]",
            "```"
        ],
        "description": "基礎 Mermaid 流程圖"
    }
}

#### 檔案範本
建立 `.mmd` 檔案範本：

flowchart TD
    %% 在這裡開始你的圖表
    Start([開始]) --> End([結束])

#### Git 整合
- ✅ 版本控制追蹤圖表變更
- ✅ 分支比較圖表差異
- ✅ 協作開發圖表文檔

---

## 在 HackMD 中使用

### 1. 基本用法
在 HackMD 中，只需要用三個反引號包圍 `mermaid` 語法：

flowchart TD
A[開始] --> B[結束]

### 2. 即時預覽
- 在編輯模式下，右側會即時顯示圖表
- 支援同步滾動，方便對照

### 3. 分享與協作
- 生成的 HackMD 連結可以直接分享
- 支援多人同時編輯
- 圖表會自動更新

---

## 本地環境匯出圖檔

### 📦 VS Code + Mermaid CLI 完整方案

#### 環境準備

# 1. 確認 Node.js 版本 
node --version  # 建議 18+ 

# 2. 在 VS Code 終端機中安裝 Mermaid CLI
npm install -g @mermaid-js/mermaid-cli

# 3. 驗證安裝
mmdc --version

#### VS Code 整合工作流程

1. **在 VS Code 中編輯**
- 建立 `.mmd` 檔案
- 使用語法高亮和即時預覽
- 利用 IntelliSense 避免語法錯誤

2. **使用內建終端機匯出**
- `Ctrl+`` (反引號) 開啟終端機
- 直接在專案目錄執行匯出指令

### 💾 VS Code 中的匯出流程

#### 1. 在 VS Code 中準備檔案

flowchart TD
    A[開始] --> B[結束]

**儲存為**: `diagram.mmd` (VS Code 會自動識別格式)

#### 2. 使用 VS Code 整合終端機
按 `Ctrl+`` 開啟終端機，執行匯出指令：

# 匯出 PNG 圖片
mmdc -i diagram.mmd -o output.png -t neutral -b white

# 匯出 SVG 向量圖 (推薦)
mmdc -i diagram.mmd -o output.svg -t neutral -b white

# 匯出高解析度 PNG
mmdc -i diagram.mmd -o output_hd.png -t neutral -b white -s 2

#### 3. 參數說明
- `-i`: 輸入檔案
- `-o`: 輸出檔案
- `-t`: 主題 (neutral, dark, forest, base 等)
- `-b`: 背景顏色
- `-s`: 縮放比例 (用於高解析度)

### 🎯 VS Code 批次匯出

建立 VS Code Task 來自動化匯出過程：

#### `.vscode/tasks.json`

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Export Mermaid to PNG",
            "type": "shell",
            "command": "mmdc",
            "args": [
                "-i", "${file}",
                "-o", "${fileDirname}/${fileBasenameNoExtension}.png",
                "-t", "neutral",
                "-b", "white"
            ],
            "group": "build",
            "presentation": {
                "echo": true,
                "reveal": "always",
                "focus": false,
                "panel": "shared"
            }
        },
        {
            "label": "Export Mermaid to SVG",
            "type": "shell",
            "command": "mmdc",
            "args": [
                "-i", "${file}",
                "-o", "${fileDirname}/${fileBasenameNoExtension}.svg",
                "-t", "neutral",
                "-b": "white"
            ],
            "group": "build"
        }
    ]
}

**使用方式**：
1. 開啟 `.mmd` 檔案
2. `Ctrl+Shift+P` → "Tasks: Run Task"
3. 選擇 "Export Mermaid to PNG" 或 "Export Mermaid to SVG"

---

## 進階技巧

### 🎨 自定義樣式

flowchart TD
    A[正常節點]
    B[重要節點]:::important
    C[警告節點]:::warning
    
    A --> B
    B --> C
    
    classDef important fill:#e1f5fe,stroke:#01579b,stroke-width:3px
    classDef warning fill:#fff3e0,stroke:#e65100,stroke-width:2px

### 🔗 添加連結

flowchart TD
    A[GitHub] --> B[專案頁面]
    click A "https://github.com" "GitHub 首頁"
    click B "https://github.com/mermaid-js/mermaid" "Mermaid 專案"

### 📝 添加註解

flowchart TD
    A[開始] --> B[處理]
    B --> C[結束]
    
    %% 這是註解，不會顯示在圖表中
    %% 用於說明邏輯或提醒

### 🌟 複雜流程圖

flowchart TB
    Start([開始]) --> Input[/輸入資料/]
    Input --> Validate{資料驗證}
    Validate -->|通過| Process[處理資料]
    Validate -->|失敗| Error[顯示錯誤]
    Process --> Save[(儲存到資料庫)]
    Save --> Success[/成功訊息/]
    Success --> End([結束])
    Error --> End
    
    style Start fill:#c8e6c9
    style End fill:#ffcdd2
    style Error fill:#ffebee,stroke:#f44336

---

## 📚 常用圖表類型

### Git Flow 圖

gitgraph
    commit id: "Initial"
    branch develop
    checkout develop
    commit id: "Feature A"
    checkout main
    merge develop
    commit id: "Release v1.0"

### 甘特圖

gantt
    title 專案時程規劃
    dateFormat  YYYY-MM-DD
    section 開發階段
    需求分析    :done, req, 2024-01-01, 2024-01-15
    系統設計    :active, design, 2024-01-16, 2024-02-01
    程式開發    :dev, 2024-02-01, 2024-03-15
    測試階段    :test, after dev, 2024-04-01

### ER 圖

erDiagram
    USER {
        int id PK
        string name
        string email UK
    }
    ORDER {
        int id PK
        int user_id FK
        datetime created_at
    }
    USER ||--o{ ORDER : places

---

## 🔧 疑難排解

### 常見問題

1. **圖表不顯示**
- 檢查語法是否正確
- 確認 HackMD 是否支援該圖表類型

2. **中文字顯示問題**
- HackMD 通常支援中文，本地匯出可能需要字型設定

3. **匯出圖片模糊**
- 使用 SVG 格式獲得最佳品質
- PNG 可以用 `-s 2` 參數提高解析度

### 最佳實踐

#### 🎯 VS Code 開發建議
- ✅ **使用工作區設定**：為專案建立專屬的 Mermaid 設定
- ✅ **版本控制**：將 `.mmd` 檔案納入 Git 管理
- ✅ **檔案組織**：建立 `docs/diagrams/` 資料夾統一管理
- ✅ **自動化**：設定 VS Code Tasks 簡化匯出流程

#### 📝 圖表設計原則
- ✅ 保持圖表簡潔，避免過於複雜
- ✅ 使用有意義的節點名稱
- ✅ 適當使用顏色和樣式區分元素
- ✅ 添加必要的註解說明
- ✅ 定期檢查圖表是否需要更新

### 🔧 VS Code 專案結構建議

project/
├── .vscode/
│   ├── settings.json     # Mermaid 相關設定
│   └── tasks.json        # 匯出自動化任務
├── docs/
│   └── diagrams/
│       ├── architecture.mmd
│       ├── workflow.mmd
│       └── exports/      # 匯出的圖片檔案
├── src/
└── README.md            # 包含圖表的專案說明

---

## 🌐 實用資源

### 📚 官方資源
- [Mermaid 官方文檔](https://mermaid.js.org/)
- [Mermaid Live Editor](https://mermaid.live/) - 線上編輯器
- [更多圖表範例](https://mermaid.js.org/syntax/examples.html)

### 🔧 VS Code 擴展市集
- [Mermaid Markdown Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=bpruitt-goddard.mermaid-markdown-syntax-highlighting)
- [Markdown Preview Enhanced](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced)
- [Mermaid Preview](https://marketplace.visualstudio.com/items?itemName=vstirbu.vscode-mermaid-preview)

### 🌐 整合平台
- [HackMD 使用指南](https://hackmd.io/features)
- [GitHub Mermaid 支援](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/)
- [GitLab Mermaid 支援](https://docs.gitlab.com/ee/user/markdown.html#mermaid)

---

## 📄 範本下載

你可以複製以下範本開始創建自己的圖表：

### 基礎流程圖範本

flowchart TD
    Start([開始]) --> Step1[步驟一]
    Step1 --> Decision{判斷條件}
    Decision -->|是| Step2[步驟二A]
    Decision -->|否| Step3[步驟二B]
    Step2 --> End([結束])
    Step3 --> End

### 系統架構圖範本

flowchart TB
    User[使用者]:::user
    Frontend[前端應用]:::frontend
    Backend[後端服務]:::backend
    Database[(資料庫)]:::database
    
    User --> Frontend
    Frontend --> Backend
    Backend --> Database
    
    classDef user fill:#e3f2fd,stroke:#1976d2
    classDef frontend fill:#f3e5f5,stroke:#7b1fa2
    classDef backend fill:#e8f5e8,stroke:#388e3c
    classDef database fill:#fff3e0,stroke:#f57c00

> 💡 **VS Code 完整工作流程**：在 VS Code 中編輯和預覽 → 本地匯出圖檔 → 複製到 HackMD 分享 → Git 版本控制管理

### 🚀 快速開始檢查清單

- [ ] 安裝 VS Code 和相關擴展
- [ ] 設定 VS Code Mermaid 環境
- [ ] 安裝 Node.js 和 Mermaid CLI
- [ ] 建立專案資料夾結構
- [ ] 設定 VS Code Tasks 自動化
- [ ] 測試圖表預覽和匯出功能
- [ ] 準備 HackMD 帳號用於分享

---

*最後更新：2025年10月 | 專為 VS Code 開發環境優化*