隨著 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