本文詳細說明如何在 Hugo 部落格中實現 Mermaid 流程圖支援，包含：

• Mermaid.js 整合與初始化
• Markdown 語法轉換處理
• 自定義樣式設計
• 響應式圖表適配
• 多種圖表類型支援

1. 問題分析

1.1 Hugo Markdown 渲染問題

Hugo 的 Markdown 渲染器會將 Mermaid 程式碼區塊包裝在 <pre><code> 標籤中：

1<pre><code class="language-mermaid">
2graph TD
3    A[開始] --> B{判斷條件}
4    B -->|是| C[執行動作]
5    B -->|否| D[結束]
6</code></pre>

但 Mermaid.js 需要的是 <div class="mermaid"> 標籤：

1<div class="mermaid">
2graph TD
3    A[開始] --> B{判斷條件}
4    B -->|是| C[執行動作]
5    B -->|否| D[結束]
6</div>

1.2 解決方案

使用 JavaScript 動態轉換 Markdown 渲染的程式碼區塊為 Mermaid 所需的格式。

2. 實現步驟

2.1 引入 Mermaid.js

在 layouts/partials/custom_head.html 中添加 Mermaid.js：

2.2 語法轉換腳本

添加 JavaScript 來轉換 Markdown 渲染的程式碼區塊：

2.3 自定義樣式

添加 Mermaid 圖表的 CSS 樣式：

3. 完整實現程式碼

3.1 custom_head.html 完整程式碼

4. 使用方式

4.1 基本語法

在 Markdown 文件中使用 Mermaid 語法：

1```mermaid
2graph TD
3    A[開始] --> B{判斷條件}
4    B -->|是| C[執行動作]
5    B -->|否| D[結束]
6    C --> D
7```

4.2 支援的圖表類型

4.2.1 流程圖 (Flowchart)

graph TD
    A[開始] --> B{判斷條件}
    B -->|是| C[執行動作]
    B -->|否| D[結束]
    C --> D

4.2.2 時序圖 (Sequence Diagram)

sequenceDiagram
    participant A as 用戶
    participant B as 系統
    participant C as 資料庫
    
    A->>B: 發送請求
    B->>C: 查詢資料
    C-->>B: 返回結果
    B-->>A: 顯示結果

4.2.3 甘特圖 (Gantt Chart)

gantt
    title 專案時程規劃
    dateFormat  YYYY-MM-DD
    section 第一階段
    需求分析           :a1, 2024-01-01, 30d
    系統設計           :a2, after a1, 20d
    section 第二階段
    程式開發           :a3, after a2, 40d
    測試驗證           :a4, after a3, 15d

4.2.4 類別圖 (Class Diagram)

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

4.2.5 狀態圖 (State Diagram)

stateDiagram-v2
    [*] --> 待機
    待機 --> 執行中 : 開始任務
    執行中 --> 完成 : 任務完成
    執行中 --> 錯誤 : 發生錯誤
    錯誤 --> 待機 : 重新開始
    完成 --> [*]

5. 自定義配置

5.1 主題設定

Mermaid 支援多種主題，可以在初始化時設定：

1mermaid.initialize({
2  theme: 'default', // 可選: default, dark, forest, neutral
3  // ... 其他設定
4});

5.2 自定義顏色

通過 themeVariables 自定義顏色：

5.3 字體設定

1mermaid.initialize({
2  fontFamily: 'Arial, sans-serif', // 字體家族
3  // ... 其他設定
4});

6. 響應式設計

6.1 桌面版樣式

1.mermaid {
2  text-align: center;
3  margin: 20px 0;
4}
5
6.mermaid svg {
7  max-width: 100%;
8  height: auto;
9}

6.2 手機版適配

7. 進階功能

7.1 互動式圖表

Mermaid 支援點擊事件和互動功能：

1mermaid.initialize({
2  startOnLoad: true,
3  securityLevel: 'loose', // 允許互動功能
4  // ... 其他設定
5});

7.2 自定義樣式

可以通過 CSS 進一步自定義圖表外觀：

8. 常見問題與解決方案

8.1 圖表不顯示

問題：Mermaid 圖表沒有渲染出來

解決方案：

1. 檢查 JavaScript 是否正確載入
2. 確認 Markdown 語法是否正確
3. 檢查瀏覽器控制台是否有錯誤訊息

8.2 樣式問題

問題：圖表樣式不符合預期

解決方案：

1. 檢查 CSS 樣式是否正確載入
2. 確認 Mermaid 初始化設定
3. 檢查是否有其他 CSS 衝突

8.3 響應式問題

問題：在手機版圖表顯示異常

解決方案：

1. 檢查響應式 CSS 設定
2. 調整字體大小和邊距
3. 測試不同螢幕尺寸

9. 效能優化

9.1 延遲載入

對於包含大量圖表的頁面，可以考慮延遲載入：

9.2 快取優化

使用 CDN 快取 Mermaid.js：

1<script src="https://cdn.jsdelivr.net/npm/mermaid@10.6.1/dist/mermaid.min.js" 
2        integrity="sha384-..." 
3        crossorigin="anonymous"></script>

10. 總結

通過這個實現方案：

1. 支援 Mermaid 語法
2. 處理 Hugo Markdown 渲染的格式問題
3. 響應式設計
4. 支援流程圖、時序圖、甘特圖等
5. 可以根據網站主題調整外觀