內容大致分三類：

規範與契約 — agent / 工具鏈行為的單一真實來源，被 AGENTS.md 或其他 config 引用：

• Blog Markdown 寫作規範與 mdtools 檢查 — 排版規則、反釣魚校驗、卡片雙向完整性的工具化契約
• Blog 文章模板設計：作者品質閘門與正文分工 — 文章模板的 blog-specific SSoT，供人類作者、Claude Code 與 Codex 共用
• 什麼是 AST — 從字串到語法樹的視角轉換 — 為什麼 blog 選 AST-based linter 而非 regex
• mdtools：Go + goldmark 的 markdown 工具鏈設計 — 子命令架構、語言選擇 tripwire、pre-commit 與 CI 整合

Hugo 與 Markdown 操作經驗 — 具體寫作與渲染問題的事故紀錄。

AI 協作與工程心得 — CI 自動除錯、技術寫作結構、專案經營相關反思。

底下自動列出本資料夾的所有文章，依日期排序。

文章模板的責任是穩定作者流程，正文的責任是承載技術文章本身。讀者進入文章時，需要看到概念、判讀、取捨與路由；作者在寫作時，需要一組欄位檢查文章是否具備可維護的最低結構。

本 blog 同時由人類作者、Claude Code 與 Codex 協作產生內容。模板若只放在單一 agent 的設定裡，就會形成工具分岔；模板若直接放進 backend 正文，又會把作者工作流暴露成讀者負擔。因此模板的單一真實來源放在 content/posts/，作為本 blog 專屬的寫作設定記錄。

放置決策

模板放置位置的核心判準是讀者與維護者是否一致。backend 文章面向技術讀者，report 面向可重用事後檢討，posts 面向 blog 自身的規範、設計與工具鏈紀錄。

這個分工讓模板同時支援 Claude Code 與 Codex，也保留文章對讀者的自然技術敘事。

模板責任

模板是品質閘門，責任是讓文章保留關鍵判準。它要檢查文章是否具備責任、判讀、風險、邊界與下一步路由，正文仍用技術文章的推導順序排列。

模板欄位可以出現在文章大綱、作者檢查清單或 agent brief 裡。正文要以技術文章方式展開，讓讀者看到推導，作者填表痕跡留在工作流內部。

Backend 技術文章最小模板

Backend 技術文章的最小模板是「概念定位 → 核心判讀 → 判讀訊號 → 風險與邊界 → 交接路由」。這組欄位適合 04 / 06 / 08 這類語言無關的後端能力文章。

 1## 概念定位
 2
 3{概念} 是 {能力 / 流程 / 控制面}，責任是 {它在系統中承擔什麼問題}。
 4
 5這一頁處理的是 {抽象層級}。它跟 {相鄰章節} 的分工是 {邊界}。
 6
 7## 核心判讀
 8
 9判讀 {概念} 時，先看 {第一判準}，再看 {第二判準}。
10
11重點訊號包括：
12
13- {訊號 1}
14- {訊號 2}
15- {訊號 3}
16
17| 判讀面向 | 最小可用判準 | 常見失真 |
18| --- | --- | --- |
19| {面向} | {判準} | {失真} |
20
21## 判讀訊號
22
23- {真實服務中會看到的徵兆}
24- {工程團隊會踩到的操作問題}
25- {事故或演練會暴露的缺口}
26
27## 交接路由
28
29- {上游章節}：{承接內容}
30- {下游章節}：{下一步處理}

這份模板只定義文章最低結構。若某篇文章需要完整案例、方案比較或實作步驟，正文可以增加章節；增加章節時仍要保留責任、判讀、風險與路由。

案例前置欄位

案例前置欄位的責任是讓服務案例能回寫到文章系統。它屬於作者拆案例時的內部欄位，正文只吸收欄位背後的判讀與取捨。

04 / 06 / 08 的案例拆解可共用這組欄位，但正文仍要用技術文章敘事。欄位幫作者維持可比性，文章幫讀者理解機制。

Agent 共用方式

Claude Code 與 Codex 共用模板時，本文是 blog 內的穩定契約。.claude/ 與 .codex/ 可以引用本文的欄位與判準，但實際模板語意以本文為準。

這個安排避免 .claude/ 與 .codex/ 各自演化成不同模板，也避免把 agent 操作細節寫進 backend 讀者正文。

使用邊界

模板適合用在多篇系列文章、跨模組路由與案例回寫。單篇短文、事故紀錄或工具使用筆記可以採較輕的結構，只要仍能說清楚核心責任與下一步。

模板開始主導正文時，需要降級成作者檢查清單。文章完成後的檢查重點是讀者能否理解技術推導，並確認欄位已在文章背後支撐判讀。

完稿檢查

完稿檢查的責任是確認技術文章維持主線。檢查時先看正文是否能獨立閱讀，再看欄位是否完整支撐交接。

• 首段是否先說概念責任
• 判讀訊號是否來自真實服務情境
• 表格項目是否有延伸說明
• 交接路由是否指向具體章節
• 案例欄位是否能回寫到 04 / 06 / 08
• 正文是否保留技術推導，並把欄位轉成讀者可理解的判讀

隨著 blog 文章與知識卡片成長，純靠寫作紀律維持排版一致性越來越不可靠。反覆踩到的問題橫跨兩個層級：

結構與安全層級（這是工具鏈存在的主要理由）：

• 裸 URL 在段落與表格中爆版（MD034），降低閱讀體驗。
• 表格管線風格混用（MD060），同一張表格有的有空白、有的沒有。
• 平行模板章節重複標題（MD024），例如多案例文章的 ### 弱點環節 出現 13 次。
• 顯示文字與實際 href 不一致（反釣魚）— 不在標準 markdownlint 規則內，但紅隊教材脈絡下必要。
• 卡片雙向完整性（orphan 卡片、斷連結、K4 合規）— 跨文件檢查，現成工具做不到。
• Front matter schema — Hugo 依賴 YAML front matter 提供 title / date / weight 等欄位，缺失會破壞列表渲染、排序、SEO。

基礎格式層級（容易被忽略但影響 parser 穩定性或語義結構）：

• 正文禁止使用 H1（嚴於 MD025）— Hugo front matter title 已產生 H1。
• 標題前後需保留空行（MD022），parser 才能正確識別標題邊界。
• 標題結尾禁止標點（MD026）— 例如 ## 常見問題： 應改為 ## 常見問題。
• 禁止用 **bold** 段落當標題（MD036）— 破壞語義階層與 TOC 產生。
• 程式碼區塊需註明語言（MD040），影響 syntax highlighting 與 accessibility。
• 列表前後需空行（MD032）、fenced code block 前後需空行（MD031）— 否則部分 parser 會把列表吃進段落。
• 有序列表編號風格一致（MD029）— 全部 1. 或全部 1./2./3.。
• 檔案結尾需有換行（MD047），POSIX 規範。
• 行長度上限（MD013）— 預設關閉，中英混用技術寫作不適用 80-char 慣例。

前兩類混合在同一份寫作規範裡，因為都由同一個工具鏈檢查、都要落地到相同的 pre-commit hook。純靠紀律記住這十幾條在大型 repo 上不可行，純 regex 又無法穩定處理「平行結構下的標題重複」「卡片段落歸屬」這類語意判斷。因此 blog 專案採用 Go + goldmark AST 做自訂 linter：scripts/mdtools。本文是 linter 與寫作規範的對齊文件；AGENTS.md 引用本文作為排版規範來源。

1. 工具總覽

工具原始碼在 scripts/mdtools/，binary build 到 bin/mdtools（已 gitignore）。

作用範圍是 content/**/*.md。public/、themes/、node_modules/ 等輸出或第三方資源不檢查。

2. 標題規則

2.1 標題結構與格式規則

• 正文禁止使用 H1。Hugo 的 front matter title 會自動產生 H1，若正文再寫 # ... 會出現兩個 H1 並列，破壞語義階層與 SEO 訊號。正文一律從 H2 開始，最深到 H6。
• 同一父標題（直接上層）底下，子標題文字必須唯一（MD024 siblings_only 模式）。
• 不同父標題底下，子標題允許重名。
• 標題前後需保留空行（MD022），mdtools fmt --fix 自動補。
• 標題結尾禁止標點（MD026）— 禁用字元：.、,、:、;、。、，、：、；。允許 ?、！、？、! 作為語氣結尾。mdtools fmt --fix 自動去除結尾禁用標點。
• 禁止用粗體當標題（MD036）— 若段落整段只由 **文字** 或 *文字* 組成，視為視覺性標題濫用。mdtools lint 只報警、不自動修；作者需手動判斷正確的標題層級（通常是 H3 / H4）並改寫。

2.2 補充範例：MD026 與 MD036 的典型誤用

MD026（標題尾標點）常見誤用：

1#### 字型選擇說明：        ← 違規（結尾 `：`）
2#### 字型選擇說明          ← 合法

中文寫作習慣用冒號引入後續內容，這個模式在「段首句」合理、在「標題」就不合理 — 標題本身的存在就暗示了後續有內容，冒號變成冗餘訊號。

MD036（粗體當標題）常見誤用：

1**字型選擇說明**           ← 違規：整段只有粗體，視覺像標題但不是真標題
2
3這段內容...
4
5### 字型選擇說明           ← 合法：用正式的 H3 取代

差異看起來微小，實際影響包含：Hugo TOC 不會抓到、卡片反向連結失效、screen reader 無法跳轉。這是「語義 vs 視覺」錯位的典型案例，AST linter 容易檢出（Paragraph 節點唯一子節點為 Strong/Emph）。

2.3 為什麼採 siblings_only 而非全域唯一

平行結構（多案例、多模板章節）的複用語義來自上層標題賦予的脈絡。例如：

1## 【案例一】Uber 2022
2### 弱點環節        ← 合法
3### 攻擊路徑
4
5## 【案例二】Okta 2023
6### 弱點環節        ← 合法，因為在不同的父層下
7### 攻擊路徑

重名只有在同層並列時才代表結構錯誤。強制全域唯一會逼作者寫 ### 【案例二】弱點環節，破壞平行結構的視覺一致性，收益並不大。

3. URL 與連結規則

3.1 裸 URL 轉換（mdtools fmt --fix 自動處理）

段落或表格儲存格內的裸 URL 會自動包成 markdown 連結。顯示文字依路徑可識別性分級：

識別碼偵測用 regex 白名單，初始清單專注在高頻識別碼格式（例如 CVE-YYYY-N），其他格式以「遇到再加」原則擴充。清單維護在 scripts/mdtools/internal/rules/identifiers.go。

3.2 反釣魚校驗（mdtools lint 強制檢查）

Markdown 語法允許顯示文字與實際 href 完全不符，這是釣魚攻擊的結構基礎。本規則在 AST 層阻擋此模式。

• R-URL-1（URL 樣顯示文字一致性）：若顯示文字含 .com / .org / .gov / .net / .io / .dev / .tw 等 TLD 字樣，則顯示文字的 domain 必須等於 href 的 domain（含子網域比對）。
• R-URL-2（描述型顯示文字自由）：顯示文字不含 TLD 字樣時，視為人類可讀描述，不做 domain 比對。

違規範例（會被 lint 阻擋）：

1[nvd.nist.gov](https://malicious.example.com/fake)     ← 顯示文字暗示 NVD，href 卻不是
2[cisa.gov/advisory](https://cisa-gov.evil.example)     ← 顯示文字抄 CISA 格式，domain 不符

合法範例：

1[Uber 事件公告](https://www.uber.com/newsroom/security-update/)
2[nvd.nist.gov/CVE-2023-34362](https://nvd.nist.gov/vuln/detail/CVE-2023-34362)

這條規則在紅隊 / 安全相關教材中特別重要：讀者本來就該對來源警戒，排版規則不該削弱這個警戒訊號。縮短顯示文字提升可讀性，反釣魚校驗守住安全底線，兩者互補。

3.3 例外情境

• 程式碼區塊（fenced code block，``` 包圍）內的 URL 不做任何處理（不縮短、不校驗）。代碼範例經常需要展示完整 URL 給讀者複製執行。
• 引用區塊（> 開頭）內的 URL 比照段落處理，會縮短也會做反釣魚校驗。

4. 表格規則

• 統一使用 aligned 風格：每欄內容用空白補齊到該欄的最大寬度，使 | 在 monospace 渲染下垂直對齊。
• 欄位分隔線使用 | --- | 形式，不含對齊冒號 :（分隔線內的 - 數量跟隨該欄寬度自動填足）。
• 寬度計算使用顯示寬度（display width）— CJK 字元佔 2 欄寬、ASCII 佔 1 欄寬，分隔列與資料列按同一套寬度對齊。
• mdtools fmt --fix 自動正規化：插入新行或改動欄寬時會全表重算，作者不需手工維持對齊。

選 aligned 而非 compact 的理由是原始檔可讀性：技術教材的表格常需在 code review 裡對照，aligned 風格讓 reviewer 直接看出哪些欄位對應哪些內容，不用在腦中解析鋸齒狀的 pipes。手工對齊在長表格反覆編輯時確實會失效（新增一行就全表要重對齊），但這正是 mdtools fmt --fix 接手的地方。

5. 基礎格式細節

這節整理容易被忽略、但會影響 parser 正確性或渲染品質的小規則。

5.1 程式碼區塊必須註明語言（MD040）

由 mdtools lint 檢查。未註明語言的 fenced code block 會被報警：

 1```                   ← 違規：缺語言標示
 2func main() {
 3    fmt.Println("hi")
 4}
 5```
 6
 7```go                 ← 合法
 8func main() {
 9    fmt.Println("hi")
10}
11```

純文字輸出（例如 terminal output、log 片段）使用 text 或 plain：

1```text
2Error: permission denied
3```

Shell 範例統一用 bash（即使是 zsh 語法，讓 syntax highlighter 有合理預設）；純設定檔依實際格式（toml、yaml、json、ini）。

5.2 fenced code block 前後需空行（MD031）

由 mdtools fmt --fix 自動處理。缺空行會讓前後段落被 parser 併入 code block 或反之。

5.3 列表前後需空行（MD032）

由 mdtools fmt --fix 自動處理。

 1上一段結束。
 2- 列表項一           ← 違規：列表前無空行，會被部分 parser 當段落延續
 3- 列表項二
 4
 5上一段結束。
 6
 7- 列表項一           ← 合法
 8- 列表項二
 9
10下一段開始。

5.4 有序列表編號一致性（MD029）

由 mdtools fmt --fix 正規化。本專案採 ordered 風格（全部遞增編號）：

11. 第一步
22. 第二步           ← 合法
33. 第三步
4
51. 第一步
61. 第二步           ← 違規：混用風格（fmt --fix 會改成 1./2./3.）
72. 第三步

選擇 ordered 的理由：原始檔可讀性高，作者直接看到步驟數；插入新項目的對齊代價比全部重新渲染低。

5.5 段落間空行

段落之間、標題前後、列表與段落之間都需空行。mdtools fmt --fix 會自動規範化多餘 / 缺失的空行，作者不需手工維護。

5.6 檔案結尾需有換行（MD047）

POSIX 文字檔規範；缺失時 git diff 會出現 \ No newline at end of file。mdtools fmt --fix 自動補。

5.7 Tab 字元（MD010）— 僅限 fenced code block

由 mdtools lint 檢查（warn 等級）。Prose / 列表 / 表格 / 引用等非 code-block 行內若出現 tab 字元，會被標記並建議改成空白；fenced code block 內的 tab 保留（Go 原始碼依 gofmt 慣例用 tab，文章要讓讀者能直接複製貼用）。

Repo 根目錄的 .markdownlint.json 用 "MD010": { "code_blocks": false } 告知 IDE 的 markdownlint extension 採用同一套 policy，讓編輯器跟 CI 的警告保持一致。

5.8 行長度上限（MD013）— 預設關閉

本規則預設關閉。中英混用的技術寫作不適用 80-char 慣例：

• 中文每字元算 1 個寬度時，80-char ≈ 40 個中文字，寫到一半就要斷行，嚴重影響可讀性。
• 中文每字元算 2 個寬度時，80-char 相當於 20-30 個中文字，更離譜。
• Markdown 編輯器普遍支援軟斷行與 IDE word wrap，實體行長度對閱讀體驗影響小。

若未來需要打開（例如發現真的有人寫出 2000-char 單行段落），建議上限 400 字元（軟上限，warn 不阻擋）。設定在 scripts/mdtools/internal/rules/config.go 的 LineLengthLimit 欄位。

5.9 裝飾符號禁用（emoji / 視覺記號）

本節本身豁免：規範要描述「哪些符號禁用」必然要列舉這些符號（use-mention distinction）。本節舉例的 emoji 屬 mention（指稱）、非 use（裝飾使用）、不違反規則。掃描指令會 hit 到本節、判讀時跳過。

content/** 正文不可使用 emoji（如 ✅ ❌ ⚠️ 🚨 🟡 🟢 ⭐ 📌 💡 ⚡ 🎯）與裝飾性 unicode 符號（✓ ✗ ✘）。表格、列表、行內標記都不行。

替換策略（emoji 承載的語意要回到文字結構、不是純粹刪除符號）：

理由：

• Grep-ability：emoji 無法用 plain text grep 命中；視覺結構容易掩蓋語意結構、reviewer 看不出「優 / 缺」是用 emoji 區分還是用標題段區分
• CLI parser 相容性：部分 multi-byte emoji 在 Rust-based CLI 工具（如某些 mdtools / pagefind / lint pipeline）觸發 char-boundary panic
• 跨語境穩定：emoji 在不同字型 / 平台 / 終端機渲染差異大、容易斷行或顯示為框

掃描指令（提交前自己跑一次、有 hit 就替換）：

1rg "✅|❌|⚠️|🚨|🟡|🟢|🔴|🟠|🔵|⭐|📌|💡|⚡|🎯|✨|📝|🔍|🛠|⛔|✓|✗|✘" content/

本規則目前未進 mdtools lint 自動掃描、靠人工 grep。未來會加進 lint pipeline。

5.10 位置引用與數量命名候選掃描（REF1 / REF2、警告層）

mdtools lint 對 content/** 跑兩個警告層掃描、來源是引用紀律卡（#155 引用章節用語意標題、#156 集合命名用角色）：

• REF1-positional-anchor：正文中的位置式引用候選 —「見第 3 點」「詳見第五章」「§4」。位置編號是當下排列的衍生值、目標是活文件時、結構重排會讓引用 silent 指向錯的內容。
• REF2-count-in-name：標題與 front matter title 中內嵌成員數的集合命名 —「六大原則」「遷移五階段流程」。成員增減時名稱先失真、且名稱是被複製最多次的字串。

兩個規則都停在警告層、命中是候選、不是判決 — 回報前要做語意判定：

掃描器內建兩個自動豁免：被 「」 包住的命中視為反例引用、直接跳過；「第」開頭的序數（第三階段）不屬 REF2 的集合命名。既有內容的命中屬歷史基線、依「changed-set scoped lint」原則處理 — 新增與修改的檔案要判讀、存量警告分開回報。

5.11 否定起手候選掃描（POS-negation-lead、警告層）

mdtools lint 對 content/** 跑否定起手掃描、來源是 #166 重點優先陳述是跨語言的資訊結構原則（搭配 #165 register 違規要文體異源）：

• POS-negation-lead：正文中「不是 X、而是 Y」「不是 X — 是 Y」「與其 X、不如 Y」的重點後置候選。核心概念（Y）被擠到「而是 / 不如」之後、讀者要先處理一個被否定的 X 才拿到重點。這是資訊結構效率問題、跨語言成立（英文「not X but Y」、日文「X ではなく Y」）、不是中文特有句型 — 偵測可機械化、判定不可。pattern 涵蓋的連接詞（而是 / 「— 是」/ 不如）枚舉不完、判準是「核心概念在不在句首」而非哪個連接詞 — 漏掉的變體只是讓候選 silent 到有人讀到（規則第一版就漏了「不是 X — 是 Y」、靠人發現才補）。

判定用「重點位置」、命中是候選、不是判決：

掃描器豁免兩類命中：被 「」 包住的引用（反例引用 / 句型佔位符）、以及 backtick 行內程式碼內的 pattern（grep regex / 技術識別碼）。講這個句型的 meta 卡（#165 / #166）與本規範段落會大量自我觸發 — 屬候選人判定豁免、跟 REF1 / REF2 對 #155 / #156 一致。既有內容的命中（全 content/ 約數百個）屬歷史基線、依「changed-set scoped lint」原則處理 — 偵測把候選池曝光、判定漸進進行、存量警告分開回報。

6. Front matter schema（mdtools lint）

Hugo 依賴 YAML front matter 提供 title / date / weight 等欄位給 render pipeline。缺欄位會讓列表頁、排序、SEO 壞掉，但 Hugo 本身不會失敗（靜默接受不完整資料），所以必須由 linter 守住。

6.1 通用層（content/**/*.md）

所有內容文章必須有：

• title：字串，不可空。
• date：YYYY-MM-DD 格式（ISO 8601 date）。

Hugo _index.md section 頁面例外：這類檔案是 Hugo 的 section 列表 landing page，不是內容文章，沒有語意上的「日期」。只要求 title，不強制 date。

6.2 推薦層（警告，不阻擋）

推薦填寫（mdtools lint warn level）：

• description：字串，建議 30–150 字，影響 SEO 與列表頁預覽。
• tags：陣列，至少 1 個標籤。

推薦層是歷史內容的緩衝區，不是新增內容的放行條件。新增文章必須同時填寫 description 與 tags；修改既有文章時，若同一檔案缺少推薦欄位，應在同次變更補齊，避免每次驗證都被舊 warning 淹沒。

驗證時先跑 changed-set scoped lint 判斷本次變更品質，再視需要跑 full lint 觀察整體基線。回報 full lint 結果時，要把歷史 warning、已知 warning 與本次新增問題分開描述。

6.3 卡片嚴格層（content/backend/knowledge-cards/**）

知識卡片額外要求（對應 .codex/briefs/knowledge-cards.md K2）：

• title、date、description 必填。
• weight：整數，決定在 _index.md 主題表格中的排序位置。

6.4 禁止欄位

以下欄位存在時 mdtools lint 警告（避免語義混淆）：

• author：本專案為單作者 blog，統一於 Hugo 設定。
• permalink：使用 Hugo 預設路徑規則，避免手動覆蓋。

若未來需要鬆綁，在 scripts/mdtools/internal/rules/frontmatter.go 的 DisallowedFields 清單調整。

6.5 slug 必填、跟檔名對齊

所有 content 文章 frontmatter 必須有 slug 欄位，值跟檔名（不含 .md）對齊。

1---
2title: "視覺手段對齊錯誤層次"
3slug: "visual-tool-error-layer-alignment"   # 跟檔名對齊
4date: 2026-04-28
5---

為什麼必填：

slug 是 URL 的核心識別、跨多個工具共用（Hugo build、mdtools lint、跨檔 markdown link、search index）。若不顯式定義，slug 散落在三處推導鏈：

三個推導鏈不一致時 = silent broken link（mdtools pass 但 hugo build 後 404、或反過來）。把 slug 升成 frontmatter 顯式 fact、所有工具基於同一 source、消除 derivation 鏈。

詳細論述見 report #93 URL slug 必須顯式定義為 fact。

檔名對齊規則：

• 檔名命名建議：英文小寫、kebab-case 或 snake_case、不含中文（避免 hugo urlize 規則跨版本變動）
• slug 值 == 檔名 stem（不含 .md）
• 修檔名時必須同步修 slug；修 slug 時必須同步 rename 檔案

Hugo _index.md 例外：section 列表頁已有 slug: 欄位指定資料夾路徑、不適用本規則。

7. 卡片雙向完整性（mdtools cards）

作用範圍：content/**/*.md，重點關注 content/backend/knowledge-cards/。

L3（正文首次出現術語必須連結到卡片）暫不納入，待術語字典（.codex/briefs/knowledge-web-expansion.md）啟動後再開。

為什麼要做跨文件檢查

知識卡片是 blog 的核心知識資產。隨著卡片數量增加：

• Orphan 卡片（沒有正文連結進來）會變成知識死角，讀者無法發現。
• 斷掉的相對連結（檔案被改名或移動）肉眼難以發現，只有讀者點擊失敗才暴露。
• K4 合規（首段 + 概念位置段要有鄰卡連結）保證卡片間的知識網不會鬆散。

這些檢查用 regex 做都卡在「段落歸屬怎麼判斷」。AST 天生知道節點的父子結構，做起來自然。

8. 執行時機

Pre-commit hook（.githooks/pre-commit）

1. mdtools fmt --fix — 自動修格式；改動會 git add 回 staged，避免改完又沒進 commit。
2. mdtools lint — 結構檢查；失敗阻擋 commit。
3. mdtools cards — 完整性檢查；失敗阻擋 commit。

Pre-push hook（.githooks/pre-push）

pre-push 的責任是把 CI 同款全量檢查提前到本機。pre-commit 為了速度只處理 staged markdown；pre-push 會跑 make check，也就是 mdtools fmt --check content/、mdtools lint content/、mdtools cards content/，讓整個 content/ 的格式與連結 drift 在推送前被攔下。

啟用 hook：

1git config core.hooksPath .githooks
2# 或：make install-hooks

CI（.github/workflows/md-check.yml）

三個子命令都跑 --check / 嚴格模式，任何違規 fail CI。

9. 寫作者使用指引

• 寫作時優先遵循本規範。pre-commit / pre-push 報錯時讀訊息修正；不可用 git commit --no-verify 或跳過 hook 的方式繞過檢查。
• 新增案例平行章節（例如多個「工具評測」「事件時序」）時不需登記到任何白名單 — siblings_only 自動判讀。
• 新增 URL 時優先採用裸 URL 轉換段的分級形式；若顯示文字含 TLD 字樣，確認 domain 與 href 完全一致。
• 新增卡片時確認首段與「概念位置」段各有至少一個相鄰卡片連結（L4 要求）；確認 front matter 含 title / date / description / weight（卡片嚴格層）。
• 程式碼區塊養成習慣先寫語言標示再填內容；純文字輸出用 text。

10. 規則擴充流程

新規則進入本文的路徑：

1. 先在 scripts/mdtools/internal/rules/ 實作為可開關的 rule（預設關）。
2. 在代表性檔案上測試誤判率。
3. 誤判率 < 1% 且有明確教材品質收益時，預設開啟並更新本文。
4. 預設開啟後同步修正既有違規；若違規數量大，可分批 PR。

11. 為什麼自訂而不是用現成 markdownlint

markdownlint-cli2 的 MD022 / MD024 / MD026 / MD029 / MD031 / MD032 / MD034 / MD036 / MD040 / MD047 / MD060 這些基礎規則都有（MD013 預設關閉、MD025 本規範嚴於原版），為什麼還要自寫？

關鍵差在卡片雙向完整性、反釣魚校驗、Front matter schema 這三類檢查，屬於跨文件 / AST 層 / 業務邏輯層的自訂邏輯，現成 linter 無法表達。這些檢查是 blog 品質的核心訊號，必須跟基礎格式檢查放在同一個工具鏈、同一次 AST parse 內處理，避免多個工具重複解析、重複維護。

另外 goldmark 是 Hugo 內建的 markdown parser。用同一個 parser 做 lint 保證「lint 通過 → Hugo render 一致」，杜絕兩套 parser 解讀不同的長尾 bug。

本文為 blog 專案 Markdown 寫作規範的單一真實來源。repo 根目錄的 AGENTS.md 引用本文作為排版規範權威，規則與 scripts/mdtools 實作保持同步。

Blog 專案的 markdown 規範有三類不同性質的檢查需求：

1. 基礎格式（MD022 / MD024 / MD034 / MD060 等）— 市面 linter 都有，但規則細節不一致，我們對 MD024 要特殊處理（siblings_only 模式允許平行結構下的同名標題）。
2. 反釣魚校驗（R-URL-1/2）— 顯示文字含 TLD 字樣時必須與 href 的 domain 一致，避免釣魚型連結。這條規則不在 markdownlint 標準集內。
3. 卡片雙向完整性（L1/L2/L4）— 跨文件的圖論檢查：每張卡片至少被一篇正文引用、相對連結目標存在、卡片首段含鄰卡連結。

三類檢查共享兩個技術需求：AST 層的語法理解、goldmark 與 Hugo render 的一致性。詳細原因寫在什麼是 AST。

Markdownlint-cli2 涵蓋第一類、無法表達第二、三類。現成方案湊不出來，就自己寫。

語言選擇：Go vs Python 的 tripwire 式決策

這是實際討論過的決策，值得留下紀錄。

表面的直覺：Blog 用 Hugo（Go 寫的），所以用 Go 最自然

這個推論有個破口：Hugo 雖然用 Go 寫，但我們用的是 pre-built binary。hugo server 本地跑的是下載好的執行檔，CI 用 peaceiris/actions-hugo 這類 action，整個 blog 的 build 流程完全不碰 Go toolchain。

「專案已有 Go 依賴」這個前提不成立。真正要問的是：我是否願意為這組工具引入 Go toolchain 這個新依賴？

務實的對比

Go 唯一的決定性優勢是 goldmark — 跟 Hugo 用同一個 parser 可以保證「lint 通過 ↔ Hugo render 成功」等價。

關鍵一問：現在需要 AST 嗎？

我們最初傾向的是 tripwire 策略：現在用 Python + regex 先頂著，等 rule 複雜度超過臨界就升級 Go + goldmark。Tripwire 條件大致是：

1. Rule 數量超過 5 條。
2. 任一規則需要「這段文字在 code block 內嗎」這類上下文判斷。
3. Hugo render 結果跟 lint 判讀開始不一致。

但事實是：

• MD024 的 siblings_only 已經需要父子關係追蹤 — 條件 2 馬上命中。
• 卡片雙向完整性是當前任務（不是未來可能）— 跨文件檢查 regex 做不到。

兩個條件當下已經滿足，delay migration 反而要兩次寫工具。所以直接選 Go + goldmark。

這個決定的邏輯層面是：當需求已在手上而非 speculative，延遲決策的代價 > 直接上的代價。

為什麼選 goldmark

三個具體理由：

1. 解析結果與 Hugo 一致

Hugo 的 content render pipeline 走 goldmark。用同一個 parser 寫 lint，可以杜絕「lint 通過但 Hugo render 失敗」或「Hugo 看得懂但 lint 誤判」這類長尾 bug。

2. AST API 直觀

Goldmark 的 AST 節點型別設計貼近 CommonMark spec：Document / Heading / Paragraph / Link / Table / FencedCodeBlock。要寫 rule 時幾乎不需要翻對照表，直接比對心中的 markdown 結構。

3. 活躍且嵌入在主流 Go 生態

Goldmark 是 Hugo 使用的 parser，社群活躍、bug fix 持續進來。不會變成 abandoned dependency。

架構設計：單一 binary + 子命令

三個檢查功能分開寫比較好懂，但如果寫成三個 binary，每次 pre-commit 都要 parse markdown 三次，對大型 repo（我們這個已經超過 300 個 markdown）會明顯拖慢。

折衷方案是單一 binary + 子命令：

 1scripts/mdtools/
 2├── go.mod
 3├── main.go                    # subcommand dispatcher
 4├── cmd/
 5│   ├── fmt.go                 # mdtools fmt [--fix|--check]
 6│   ├── lint.go                # mdtools lint
 7│   └── cards.go               # mdtools cards
 8├── internal/
 9│   ├── astutil/               # goldmark 封裝（parse, walk, parent chain）
10│   ├── rules/                 # 規則定義（可被三個子命令共用）
11│   │   ├── config.go          # 全域開關與參數
12│   │   ├── headings.go        # 標題規則
13│   │   ├── urls.go            # URL + 反釣魚
14│   │   ├── tables.go          # 表格正規化
15│   │   ├── frontmatter.go     # front matter schema
16│   │   └── identifiers.go     # 識別碼白名單（CVE、KB、...）
17│   └── report/                # 統一錯誤輸出格式
18└── README.md

三個子命令共享 internal/astutil 和 internal/rules，同一個 parse 結果可以在不同規則間重用。

實際走訪：MD024 siblings_only 在 goldmark 上怎麼寫

這段是示範 AST-based rule 的可讀性，不是最終實作版本。

 1package rules
 2
 3import (
 4    "bytes"
 5
 6    "github.com/yuin/goldmark/ast"
 7    "github.com/yuin/goldmark/text"
 8)
 9
10// CheckSiblingsOnlyHeadings walks the document and flags headings
11// that share the same text with a sibling under the same parent heading.
12func CheckSiblingsOnlyHeadings(doc ast.Node, src []byte) []Violation {
13    var violations []Violation
14
15    // parentMap[level] 保留目前走到的各層 heading，作為後續 H(n+1) 的 parent context
16    parentMap := map[int]*ast.Heading{}
17    // 每個 parent context 下，收集已見過的子 heading 文字
18    seenUnderParent := map[*ast.Heading]map[string]ast.Node{}
19
20    ast.Walk(doc, func(n ast.Node, entering bool) (ast.WalkStatus, error) {
21        if !entering {
22            return ast.WalkContinue, nil
23        }
24
25        h, ok := n.(*ast.Heading)
26        if !ok {
27            return ast.WalkContinue, nil
28        }
29
30        text := string(h.Text(src))
31        parent := parentMap[h.Level-1] // 直接上層 heading
32        seen, exists := seenUnderParent[parent]
33        if !exists {
34            seen = map[string]ast.Node{}
35            seenUnderParent[parent] = seen
36        }
37
38        if prev, dup := seen[text]; dup {
39            violations = append(violations, Violation{
40                Rule:    "MD024-siblings_only",
41                Node:    h,
42                Message: "duplicate heading under the same parent: " + text,
43                Prev:    prev,
44            })
45        } else {
46            seen[text] = h
47        }
48
49        parentMap[h.Level] = h
50        // 進到更深層時，清空下層的舊狀態
51        for lv := h.Level + 1; lv <= 6; lv++ {
52            delete(parentMap, lv)
53        }
54
55        return ast.WalkContinue, nil
56    })
57
58    return violations
59}

對比 regex 版本要自己寫「目前 H2 是誰」狀態機 + 「切回上層時清狀態」— goldmark 的 walker pattern 把階層邏輯外部化到樹結構，rule 本身只處理「同一 parent 下有沒有重複」的核心語義。

幾百行 regex 才能穩定做到的事，AST 版本大概 30 行。規則越多，這個倍率越明顯。

Pre-commit 與 CI 整合

本地開發：.githooks/pre-commit 與 .githooks/pre-push

 1#!/usr/bin/env bash
 2set -euo pipefail
 3
 4# 確保 binary 最新
 5if [[ ! -x bin/mdtools ]] || [[ scripts/mdtools/main.go -nt bin/mdtools ]]; then
 6    echo "Rebuilding mdtools..."
 7    (cd scripts/mdtools && go build -o ../../bin/mdtools .)
 8fi
 9
10# 三段式檢查
11bin/mdtools fmt --fix   # 自動修格式；改動會 re-stage
12git add $(git diff --name-only --cached --diff-filter=AM | grep '\.md$' || true)
13
14bin/mdtools lint        # 結構檢查，失敗即阻擋
15bin/mdtools cards       # 跨文件檢查，失敗即阻擋

pre-push 補上全量 gate：

1make check

關鍵設計：

• mdtools fmt --fix 會改檔，改完後要 git add 回 staged，否則 commit 進去的還是舊內容。
• lint 和 cards 不改檔，只讀與報告。
• pre-commit 保持 staged-file scoped，讓 commit 回饋夠快；pre-push 跑全量 make check，讓本機結果和 CI 同步。
• Binary mtime 檢查避免每次 commit 都 rebuild。
• bin/mdtools 本身 gitignore，不 commit 進 repo。

CI：.github/workflows/md-check.yml

 1name: md-check
 2on: [push, pull_request]
 3
 4jobs:
 5  check:
 6    runs-on: ubuntu-latest
 7    steps:
 8      - uses: actions/checkout@v4
 9      - uses: actions/setup-go@v5
10        with: { go-version: 'stable' }
11      - name: Build mdtools
12        run: (cd scripts/mdtools && go build -o ../../bin/mdtools .)
13      - name: Format check
14        run: bin/mdtools fmt --check
15      - name: Structural lint
16        run: bin/mdtools lint
17      - name: Cross-file completeness
18        run: bin/mdtools cards

CI 用 --check 而非 --fix — 任何格式偏差都 fail，不自動修（避免 CI 把修復 commit 推回去造成誤會）。

安裝 hook

1git config core.hooksPath .githooks
2# 或用 Makefile target：
3make install-hooks

維運成本的長期考量

誤判率是規則生命週期的關鍵

每條規則都可能誤判。我們的處理策略寫在規範的規則擴充流程段：

1. 新規則先在 internal/rules/ 實作為可開關（預設關）。
2. 在代表性檔案上測試誤判率。
3. 誤判率 < 1% 且有明確教材品質收益時，預設開啟。
4. 預設開啟後，同步修正既有違規。

關鍵在「預設關閉」這一步 — 給規則一個試水期，不會直接擋 commit。

規則與 spec 文件的同步

Rule config 在 internal/rules/config.go，spec 文件在 content/posts/markdown-writing-spec.md。兩者修改時必須同步，否則會出現「spec 寫的規則跟工具實際跑的規則不同步」的沉默 bug。

這是目前靠紀律維持的部分。未來如果發現同步偏差重複發生，可以考慮從 config.go 產生 spec 的片段（或反過來）。目前手動同步的成本還可接受。

規則數量的預期曲線

當前覆蓋 22 條 rule-config 條目。接下來加規則的收益會遞減 — 大部分重要的基礎格式 + 結構 + 跨文件檢查都已在內。未來新增應該集中在：

• 新內容類型帶來的 schema 擴充（例如做 podcast 或者 video posts）。
• 術語字典完成後的 L3 術語覆蓋（正文首次出現術語自動連卡片）。
• 特定領域的品質檢查（例如紅隊教材「每個案例必須有 3 來源」）。

基礎 markdownlint 規則能加的都加完了，再追規則就是在吸邊際收益極低的條目，不值得。

延伸閱讀

• 什麼是 AST — 從字串到語法樹的視角轉換 — 為什麼要升級到 AST 工具鏈
• Blog Markdown 寫作規範與 mdtools 檢查 — mdtools 檢查的完整規則清單
• goldmark 官方 repo — Hugo 所用的 markdown parser
• goldmark AST package reference — ast.Walk、節點型別、parent traversal API

最初的問題很小：blog 文章數量成長後，每次 commit 都會收到 markdownlint 的同類警告反覆出現。有三個代表性的：

• MD034/no-bare-urls — 裸 URL 散落在段落與表格。
• MD024/no-duplicate-heading — 平行結構章節（例如 13 個案例各自有 ### 弱點環節）全部被判重複。
• MD060/table-column-style — 表格管線前後空白不一致。

前兩個用現成工具 --fix 不一定修得乾淨，因為 MD024 的「重複」在我們的語境下是合法的平行結構（不同父標題下重名其實是特色），而「裸 URL 轉換」要處理表格儲存格、程式碼區塊等特殊情境，單純 regex 會誤判。

討論到後來關鍵字出現：要做得精確，可能要用 AST 工具，而不是 regex 工具。

那麼 AST 到底是什麼？跟我們熟悉的 regex / 字串處理差在哪？

Regex 工具看世界的方式：字元序列

Regex 工具處理 markdown 的方式是「逐行掃描 + pattern matching」。它看到的是字元流，沒有語法結構的概念。

舉個例子：

1## 【案例一】Uber 2022
2
3事件中攻擊者取得 `session_token`，參考：
4https://www.uber.com/newsroom/security-update/
5
6| 事件      | 來源             |
7| --------- | ---------------- |
8| Uber 2022 | https://uber.com |

Regex 工具看到的是：

1Line 1: "## 【案例一】Uber 2022"            ← ^#{1,6} match  → heading
2Line 3: "事件中攻擊者取得 `session_token`..."  ← 無 pattern 命中
3Line 4: "https://www.uber.com/..."            ← ^https?:// match → bare URL!
4Line 7: "| Uber 2022 | https://uber.com |"   ← ^\| match     → table row

每一行獨立判讀，沒有上下文。Regex 工具不知道 line 4 到底是「段落的一部分」、「引用區塊裡的連結」、還是「程式碼範例」。它只看 pattern。

AST 工具看世界的方式：語法樹

AST = Abstract Syntax Tree，抽象語法樹。AST 工具先把整段 markdown 用 parser 解析成結構化的樹，然後工具在樹上走訪（traverse），操作「節點」而不是「行」。

同一段 markdown，goldmark（Hugo 內建的 markdown parser）解析後的樹大致是：

 1Document
 2├── Heading (level=2)
 3│   └── Text: "【案例一】Uber 2022"
 4├── Paragraph
 5│   ├── Text: "事件中攻擊者取得 "
 6│   ├── CodeSpan: "session_token"            ← 知道這是 inline code
 7│   ├── Text: "，參考："
 8│   └── AutoLink: "https://www.uber.com/..."  ← 知道這是段落中的裸 URL
 9└── Table
10    ├── TableHeader: [事件, 來源]
11    └── TableRow
12        ├── TableCell: "Uber 2022"
13        └── TableCell: AutoLink "https://uber.com"  ← 知道這是表格儲存格中的 URL

對同一個 URL，AST 工具能分辨「它在段落裡」還是「它在表格儲存格裡」還是「它在程式碼區塊裡」— 因為節點的父子關係已經是樹的一部分。

這個差異乍看像技術細節，實際影響的是能寫出什麼樣的規則。

典型意外情境：regex 會誤判的三個 case

程式碼區塊內的 URL

1## 測試範例
2
3```bash
4curl https://example.com/api  # 這是程式碼範例，不該報 MD034
5```

Regex 看到 https:// 開頭就標記裸 URL。AST 知道這一行在 FencedCodeBlock 子樹內，跳過。

Front matter 裡的 # 被當 heading

1---
2title: "Python 的 # 註解語法"
3---
4
5真正的文章內容...

Regex 看到 ^# 就當 heading 記一筆（title 裡面有 # 字元）。AST 知道 ---...--- 區塊是 YAML front matter，title 的值是字串。

平行結構標題被誤判為重複

在多案例教材裡：

1## 【案例一】Uber 2022
2
3### 弱點環節 ← 第 1 次出現
4
5### 攻擊路徑
6
7## 【案例二】Okta 2023
8
9### 弱點環節 ← 第 2 次出現，regex 會直接報重複

要用 regex 實作「不同父標題下允許重複」這種 siblings_only 規則，需要自己維護狀態機追蹤「目前 H2 是誰」「遇到 H3 時算哪個 H2 底下」。遇到 H4/H5 階層更複雜。

用 AST，父子關係已經內建在樹結構裡：

1// 偽代碼，實際用 goldmark walker 取代
2for _, h2 := range allHeadingsAtLevel(doc, 2) {
3    children := childrenOfType(h2, Heading)
4    checkDuplicates(children)  // 自動只比對同一 H2 下的子標題
5}

不用追蹤狀態，邏輯上直接表達。

為什麼對我們特別重要：goldmark = Hugo 的 parser

Hugo（blog 的 static site generator）內建的 markdown parser 就是 goldmark。用 goldmark 寫 lint 有個平凡但關鍵的保證：lint 的判讀跟 Hugo render 的判讀完全一致。

如果用不同的 parser 寫 lint（例如 Python 的 mistune、JavaScript 的 markdown-it），很可能遇到這種尷尬：

• Lint 通過，但 Hugo 解析不出來，render 失敗或跑版。
• Lint 報錯，但 Hugo 看得懂、實際沒有問題。

兩套 parser 解讀差異是長尾 bug 的溫床。用同一個 parser 可以從源頭杜絕這類不一致。

什麼時候 AST 不是必要的

不要為了「比較先進」就上 AST。Regex 在下列情境完全夠用：

• 檢查每行開頭字元（^#、^|、^- ）。
• 簡單字串替換（例如 URL 前後加 <> 包裹）。
• 不需要知道上下文的格式正規化（行尾空白、tab 轉空白）。

需要 AST 才能穩定做到的是：

• 判斷「這段文字在 code block 內嗎？」
• 判斷「這個 heading 的父 heading 是誰？」
• 追蹤跨文件的連結關係（卡片 backlink 完整性）。
• 檢查「這個 Strong 節點是不是整個段落的唯一子節點？」（MD036 粗體當標題濫用）

一個實務判準：如果 rule 需要「知道這段文字處在什麼結構中」，regex 會卡住；AST 天生就有這個資訊。

我們的判斷：什麼時機該升級到 AST

blog 專案一開始也考慮過用 Python + regex 先頂著，等規則變複雜再升級 Go + goldmark。後來有兩件事讓我們直接選 AST：

1. MD024 siblings_only 已經是「需要上下文」的規則，regex 做得到但會寫得脆弱。
2. 知識卡片雙向完整性是當前在做的工作（每張卡片要被正文連到、每張卡片首段要有鄰卡連結），這類跨文件 + 段落歸屬的檢查，regex 做不出來。

當需求已經在手上，延遲決策反而更貴。對我們來說，AST 不是超前部署，是現在的 blocker。

延伸閱讀

• Blog Markdown 寫作規範與 mdtools 檢查 — 所有規則的正式契約
• mdtools：Go + goldmark 的 markdown 工具鏈設計 — 如何把 AST 能力組裝成 pre-commit hook
• goldmark 官方 repo — Hugo 所用的 markdown parser

在撰寫技術文章時，我們會在文章中加入程式碼範例。但是 blog 的目標是分享我處理問題的思路，而不是提供解決方案，所以我希望預設把程式碼隱藏。

最初的解決方案

使用 HTML5 的 <details> 和 <summary> 標籤：

1<details>
2<summary>點擊查看程式碼</summary>
3
4\```javascript
5console.log('Hello World');
6\```
7
8</details>

這個方案雖然功能正常，但會觸發 MD033 Markdown Linter 警告：

1MD033/no-inline-html: Inline HTML [Element: details]

為什麼會有這個警告？

Markdown 設計哲學

Markdown 的設計理念是：

• 保持純文字的可讀性
• 避免直接使用 HTML 標籤
• 使用語義化的標記語法

MD033 規則的目的

MD033 規則旨在：

1. 維持 Markdown 的純淨性：避免 HTML 與 Markdown 混用
2. 提升可維護性：純 Markdown 更容易閱讀和維護
3. 確保相容性：不同的 Markdown 渲染器對 HTML 的支援程度不同

Hugo Shortcode 解決方案

什麼是 Shortcode？

Hugo Shortcode 是 Hugo 靜態網站生成器提供的一個強大功能，允許你：

• 在 Markdown 中使用自定義的簡短標記
• 封裝複雜的 HTML 結構
• 保持 Markdown 文件的整潔

優勢分析

實現步驟

步驟 1：創建 Shortcode 檔案

在專案根目錄創建 layouts/shortcodes/details.html：

 1{{/* 
 2  Details shortcode - 用於創建可折疊的內容區塊
 3  
 4  使用方式:
 5  
 6
 7<details>
 8  <summary>點擊展開</summary>
 9  
10  內容...
11  
12</details>
13  
14  參數:
15  - summary: 摘要文字（可選，預設為 "點擊展開"）
16*/}}
17<details>
18  <summary>{{ .Get "summary" | default "點擊展開" }}</summary>
19  {{ .Inner | markdownify }}
20</details>

程式碼說明：

1. 註解區塊：{{/* ... */}} 用於說明 shortcode 的用途和使用方式
2. 參數獲取：.Get "summary" 獲取 summary 參數
3. 預設值：default "點擊展開" 提供預設文字
4. 內容處理：.Inner 獲取標籤內的內容
5. Markdown 渲染：markdownify 將內容中的 Markdown 語法轉換為 HTML

步驟 2：在 Markdown 中使用

舊方式（會觸發 MD033）

 1<details>
 2<summary>點擊查看程式碼</summary>
 3
 4\```toml
 5[markup]
 6  [markup.tableOfContents]
 7    startLevel = 2
 8\```
 9
10</details>

新方式（符合 Markdown 規範）

1


  
點擊查看程式碼
  

\```toml
[markup]
  [markup.tableOfContents]
    startLevel = 2
\```

步驟 3：添加 CSS 樣式

在 layouts/partials/custom_head.html 中添加樣式：

 1/* 可折疊程式碼區塊樣式 */
 2details {
 3  margin: 1.5rem 0;
 4  padding: 1rem;
 5  background: rgba(0, 0, 0, 0.05);
 6  border-radius: 8px;
 7  border: 1px solid rgba(0, 0, 0, 0.1);
 8  transition: all 0.3s ease;
 9}
10
11details:hover {
12  background: rgba(0, 0, 0, 0.08);
13  border-color: rgba(0, 0, 0, 0.15);
14}
15
16details[open] {
17  background: rgba(0, 0, 0, 0.03);
18  border-color: rgba(0, 0, 0, 0.2);
19}
20
21summary {
22  cursor: pointer;
23  font-weight: 600;
24  font-size: 0.95rem;
25  padding: 0.5rem;
26  margin: -1rem -1rem 0 -1rem;
27  border-radius: 8px 8px 0 0;
28  background: rgba(0, 0, 0, 0.05);
29  transition: all 0.2s ease;
30  user-select: none;
31  list-style: none;
32}
33
34summary::-webkit-details-marker {
35  display: none;
36}
37
38summary::before {
39  content: '▶';
40  display: inline-block;
41  margin-right: 0.5rem;
42  transition: transform 0.3s ease;
43  font-size: 0.8rem;
44}
45
46details[open] summary::before {
47  transform: rotate(90deg);
48}
49
50summary:hover {
51  background: rgba(0, 0, 0, 0.1);
52}
53
54details[open] summary {
55  margin-bottom: 1rem;
56  border-bottom: 1px solid rgba(0, 0, 0, 0.1);
57  border-radius: 8px 8px 0 0;
58}
59
60/* 確保 details 內的程式碼區塊樣式正常 */
61details pre {
62  margin: 1rem 0 0 0;
63}
64
65details > *:not(summary) {
66  animation: fadeIn 0.3s ease;
67}
68
69@keyframes fadeIn {
70  from {
71    opacity: 0;
72    transform: translateY(-10px);
73  }
74  to {
75    opacity: 1;
76    transform: translateY(0);
77  }
78}
79
80/* 響應式設計 */
81@media (max-width: 768px) {
82  details {
83    margin: 1rem 0;
84    padding: 0.8rem;
85  }
86
87  summary {
88    font-size: 0.9rem;
89    padding: 0.4rem;
90    margin: -0.8rem -0.8rem 0 -0.8rem;
91  }
92}

進階功能

自定義參數

你可以擴展 shortcode 支援更多參數：

 1{{/*
 2  進階 Details shortcode
 3  
 4  參數:
 5  - summary: 摘要文字
 6  - open: 是否預設展開（true/false）
 7  - class: 自定義 CSS 類別
 8*/}}
 9<details {{ if .Get "open" }}open{{ end }} {{ with .Get "class" }}class="{{ . }}"{{ end }}>
10  <summary>{{ .Get "summary" | default "點擊展開" }}</summary>
11  {{ .Inner | markdownify }}
12</details>

使用範例：

1


  
重要提示
  
這個區塊預設是展開的

巢狀使用

Shortcode 支援巢狀使用：

1


  
外層標題
  

這是外層內容




  
內層標題
  
這是內層內容

遷移指南

批量替換

如果你已經有很多使用 HTML 標籤的文章，可以使用以下步驟批量替換：

步驟 1：備份檔案

1git commit -am "備份：準備遷移到 shortcode"

步驟 2：使用 sed 批量替換（macOS）

 1# 替換開始標籤
 2find content -name "*.md" -type f -exec sed -i '' \
 3  's/<details>$/{{&lt; details summary="點擊查看程式碼" &gt;}}/g' {} +
 4
 5# 替換帶 summary 的開始標籤
 6find content -name "*.md" -type f -exec sed -i '' \
 7  's/<details>.*<summary>\(.*\)<\/summary>/{{&lt; details summary="\1" &gt;}}/g' {} +
 8
 9# 替換結束標籤
10find content -name "*.md" -type f -exec sed -i '' \
11  's/<\/details>/{{&lt; \/details &gt;}}/g' {} +

步驟 3：驗證結果

1# 檢查是否還有 HTML 標籤
2grep -r "<details>" content/
3grep -r "</details>" content/

步驟 4：測試並提交

1hugo server -D
2# 確認無誤後提交
3git add .
4git commit -m "遷移到 shortcode：移除 HTML 標籤"

常見問題

Q1: Shortcode 不生效？

可能原因：

1. 檔案路徑錯誤：確認檔案在 layouts/shortcodes/ 目錄
2. 檔案名稱錯誤：檔案名稱應該是 details.html
3. Hugo 版本過舊：確認 Hugo 版本 >= 0.55

解決方案：

1# 檢查 Hugo 版本
2hugo version
3
4# 重新啟動 Hugo server
5hugo server -D --disableFastRender

Q2: Markdown 內容沒有被渲染？

問題：shortcode 內的 Markdown 語法沒有被轉換為 HTML

解決方案：

確認使用了 markdownify 函數：

1{{ .Inner | markdownify }}

Q3: 如何處理全域 gitignore 規則？

如果你的專案需要追蹤 .claude/settings.local.json，但被全域 gitignore 排除：

方案 1：強制添加

1git add -f .claude/settings.local.json

方案 2：在專案 .gitignore 中覆蓋

# 允許追蹤 .claude/settings.local.json
!.claude/settings.local.json

Q4: CSS 樣式沒有生效？

檢查清單：

1. 確認 CSS 是否正確載入到 custom_head.html
2. 確認瀏覽器快取是否清除（Ctrl+Shift+R 強制重新整理）
3. 確認 CSS 選擇器是否正確
4. 確認是否有其他 CSS 覆蓋了樣式

效能考量

Shortcode vs HTML 標籤

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