Hugo 部落格支援 Mermaid 流程圖完整實現指南

2025-10-08

概述

本文詳細說明如何在 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：

點擊查看引入程式碼

```html ```

2.2 語法轉換腳本

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

點擊查看語法轉換 JavaScript 程式碼

```html ```

2.3 自定義樣式

添加 Mermaid 圖表的 CSS 樣式：

點擊查看 CSS 樣式程式碼

```html```

3. 完整實現程式碼

3.1 custom_head.html 完整程式碼

點擊查看完整實現程式碼

```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 自定義顏色：

點擊查看自定義顏色程式碼

```javascript mermaid.initialize({ themeVariables: { primaryColor: '#2d3748', // 主要顏色 primaryTextColor: '#2d3748', // 主要文字顏色 primaryBorderColor: '#4a5568', // 主要邊框顏色 lineColor: '#4a5568', // 線條顏色 secondaryColor: '#e2e8f0', // 次要顏色 tertiaryColor: '#f7fafc' // 第三級顏色 } }); ```

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 手機版適配

點擊查看手機版適配 CSS

```css @media (max-width: 768px) { .mermaid { font-size: 12px; margin: 15px 0; } } ```

7. 進階功能

7.1 互動式圖表

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

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

7.2 自定義樣式

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

點擊查看進階自定義樣式 CSS

```css .mermaid .node rect { fill: #f9f9f9; stroke: #333; stroke-width: 2px; } .mermaid .edgePath .path { stroke: #333; stroke-width: 2px; } .mermaid .edgeLabel { background-color: #e8e8e8; } ```

8. 常見問題與解決方案

8.1 圖表不顯示

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

解決方案：

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

8.2 樣式問題

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

解決方案：

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

8.3 響應式問題

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

解決方案：

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

9. 效能優化

9.1 延遲載入

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

點擊查看延遲載入程式碼

```javascript // 只在圖表進入視窗時才初始化 const observer = new IntersectionObserver((entries) => { entries.forEach(entry => { if (entry.isIntersecting) { // 初始化 Mermaid mermaid.init(undefined, entry.target); observer.unobserve(entry.target); } }); }); document.querySelectorAll('.mermaid').forEach(el => { observer.observe(el); }); ```

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. 總結

通過這個實現方案：

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

#hugo #mermaid #流程圖 #圖表 #markdown