背景：本文是「Hugo 部落格支援 Mermaid 流程圖完整實現指南」的補洞紀錄。原指南建立了 Mermaid 整合的基礎、但 gitGraph 的自訂 commit type 顏色設定沒包含進去、文章用到才發現渲染失效。

問題情境

部落格用 Hugo + Mermaid 10.6.1 畫 gitGraph，文章裡寫了 type: HIGHLIGHT 和 type: REVERSE 想標出特定 commit、但渲染出來全部是預設灰色、type 標記沒生效。

gitGraph
   commit id: "A" type: HIGHLIGHT
   commit id: "C" type: REVERSE

期望：HIGHLIGHT 綠色、REVERSE 紅色 實際：兩個都跟普通 commit 一樣灰

根本原因

layouts/partials/custom_head.html 的 mermaid.initialize() 裡 themeVariables 只設了通用顏色（primaryColor、secondaryColor 等）、沒給 gitGraph 專用的顏色變數。Mermaid 找不到 HIGHLIGHT / REVERSE 對應的顏色就 fallback 到預設值。

 1// 原本的配置（不完整）
 2themeVariables: {
 3  primaryColor: '#2d3748',
 4  primaryTextColor: '#2d3748',
 5  primaryBorderColor: '#4a5568',
 6  lineColor: '#4a5568',
 7  secondaryColor: '#e2e8f0',
 8  tertiaryColor: '#f7fafc'
 9  // 缺：git0 / git1 / git2 等 gitGraph 變數
10}

Mermaid 的 themeVariables 對不同圖表類型有不同的命名空間 — flowchart 用 primaryColor、gitGraph 用 git0 / git1 / git2。原本的配置只覆蓋到通用 / flowchart 的命名空間。

解法

兩層補洞：JS 層補 themeVariables、CSS 層補 selector 規則做雙保險。

1. themeVariables 加 gitGraph 顏色

1themeVariables: {
2  // 原本的通用顏色保留
3  // ...
4
5  // 補 gitGraph 顏色
6  git0: '#90ee90',    // HIGHLIGHT
7  git1: '#ffb6c6',    // REVERSE
8  git2: '#4a5568'     // 其他
9}

2. CSS selector 補強

光靠 themeVariables 在某些 Mermaid 版本仍不穩定（命名規則隨版本改變、見下方注意事項）、加 CSS 直接針對渲染後的 SVG 元素：

1.mermaid svg [id$="_HIGHLIGHT"] circle {
2  fill: #90ee90;
3  stroke: #2d7a2d;
4}
5
6.mermaid svg [id$="_REVERSE"] circle {
7  fill: #ffb6c6;
8  stroke: #d32f2f;
9}

Mermaid 渲染 gitGraph 時、會在每個 commit 的 SVG node 加上 id="..._HIGHLIGHT" / id="..._REVERSE"、用 attribute selector [id$="_TYPENAME"] 命中。

注意事項

• 顏色變數命名隨 Mermaid 版本變動：10.6.1 用 git0 / git1 / git2、更早版本可能是 gitInv0 / gitInv1。升級 Mermaid 版本時要驗證一次顏色設定還生效。
• CSS selector 是防禦性的：themeVariables 配對的話 CSS 不會生效、但 themeVariables 失靈時 CSS 接住。雙保險、不重複設值。
• 這篇只解決「顏色沒出來」這個視覺問題：寫文章引用 gitGraph 的過程中還發現另一個議題 —「用 emoji 圖例區分 HIGHLIGHT / REVERSE」本身是語意混淆、不是視覺問題、修 CSS 解不了。那個議題見 report #92 視覺手段對齊錯誤層次。

驗證

修改後在本地 Hugo dev server 預覽包含 gitGraph 的文章、確認：

• HIGHLIGHT 的 commit circle 顯示綠色
• REVERSE 的 commit circle 顯示紅色
• 沒有 type 的 commit 維持預設灰色

本文詳細說明如何在 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. 可以根據網站主題調整外觀