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

靜態站沒有後端可以接查詢，所有搜尋工作必須在兩個時點之一完成：build 時產生索引、client runtime 執行匹配。這個前提決定了所有靜態站搜尋方案共同面對的兩個設計軸：

方案差異來自這兩軸的組合。Pagefind 選的是「build 時產生、按需載入」，它的所有設計決策都是這個選擇的延伸。

核心設計：索引切片與按需載入

商業邏輯：搜尋索引的 scaling 關鍵是單次查詢需要下載多少資料，而非壓縮率或演算法效率。若索引是一整包、每次查詢都要先整包載入，訪客體驗與站的大小線性綁定 — 站大 10 倍，首次搜尋延遲 10 倍。

要脫離這條綁定，索引必須能以「與查詢相關」的粒度切片、按需傳輸。這把「索引多大」的問題從訪客手上移回 build pipeline。

CASE：Pagefind 的索引是三層結構：

查「WAF」時，client 下載路徑是：entry（10KB）→ 涵蓋 “W” 的 index chunk（~30KB）→ 命中文章的 fragment（每筆 3KB）。總傳輸量與全站大小幾乎脫鉤 — 站擴大 10 倍，單次搜尋仍然只下載「W」那個 chunk 與少數 fragment。

架構選擇：爬 rendered HTML

商業邏輯：索引內容的來源有兩種可能：source 層（markdown、frontmatter、結構化資料）或 output 層（render 後的 HTML）。選哪一層決定工具與 framework 的耦合程度 — source 層要求工具懂特定 framework 的內容模型；output 層只要求結果是 HTML。

Pagefind 選 output 層。含義是：它跟 Hugo、Jekyll、Zola、Next.js static export 完全解耦，只要該 framework 產出的是 HTML，Pagefind 都能索引。

CASE：此選擇在 blog 端的具體要求：希望被搜到的內容必須出現在 rendered HTML 上。frontmatter 的 description 欄位若只存在於 markdown source、沒被 theme 輸出成 <meta> 或可見文字，就不會進索引。

這個 blog 天然滿足 — theme 把 description 寫進 <meta name="description">，render hook 也用它做 tooltip。移植到任何其他 static site generator，只要目標的 output HTML 有這些欄位，搜尋整合不用重寫。

整合步驟

1. Build pipeline

核心動作：Hugo build 後加一步 Pagefind。

1hugo --minify
2npx -y pagefind --site public

兩步，沒有中間檔。Pagefind 自行讀取 public/ 的 HTML，將索引寫回 public/pagefind/。

2. 搜尋頁路由

核心動作：建立 Hugo 單頁，指向專屬 layout。

1---
2title: "搜尋"
3layout: search
4sitemap:
5  disable: true
6---

sitemap.disable 避免搜尋頁自己被 Hugo sitemap 收錄。

3. UI 掛載

核心動作：在 layout 中載入 Pagefind UI 資源，指定 mount point。

 1{{ define "main" }}
 2<div data-pagefind-ignore>
 3  <link href="{{ "pagefind/pagefind-ui.css" | relURL }}" rel="stylesheet">
 4  <div id="search"></div>
 5  <script src="{{ "pagefind/pagefind-ui.js" | relURL }}"></script>
 6  <script>
 7    window.addEventListener('DOMContentLoaded', function () {
 8      new PagefindUI({
 9        element: "#search",
10        showSubResults: true,
11        translations: { placeholder: "搜尋卡片或文章…" }
12      });
13    });
14  </script>
15</div>
16{{ end }}

兩個細節：

• data-pagefind-ignore 告訴 Pagefind 這頁本身不要進索引（避免搜「搜尋」出現搜尋頁）。
• relURL 處理 baseURL 的 subpath（例如 /blog/），讓 UI 自動推斷 chunk 相對位置。

4. CI workflow

核心動作：GitHub Actions 在 Hugo build 步驟後插入 Pagefind。

1- name: Build Pagefind search index
2  run: npx -y pagefind --site public

ubuntu-latest runner 內建 node，npx -y 首次執行會下載並 cache binary，後續執行直接從 cache 取用。

方案的內在屬性

評估 Pagefind 不看「比較快」「比較省事」這類時間維度，用下列內在屬性：

內建的一等公民特性：

• Filter by facet：data-pagefind-filter="type:card" 標在 HTML 元素上，UI 自動出現對應 filter checkbox
• Snippet highlighting：命中的關鍵字在結果摘要中高亮
• 無障礙：Component UI（1.5.0+）內建 keyboard navigation、ARIA label、screen reader 公告

這些特徵都源自「build 時產生 + 按需載入」這個核心選擇的延伸，不是外掛功能。

運作特徵

zh-tw 走 character n-gram

核心定義：Pagefind 對非空白分詞語言採 n-gram — 以字元序列作為匹配單位，而非詞。

行為：搜「負載平衡」能命中「負載平衡器」、「負載平衡器測試」等任何包含該字元序列的頁面。啟動時會印一行 stemming note，那是針對屈折變化語言（英文、德文）的 stemming 提示，對中文無意義也無限制。

邊界：少數情境下跨詞邊界的字元組合會誤命中（例如搜「負載過」可能命中「負載過高」與「負載過往」）。在名詞為主的技術站影響極小。

索引來自 rendered HTML

核心定義：索引內容 = Pagefind 在 public/*.html 看到的可見文字與 meta tag。

含義：想加入索引的欄位必須出現在 output HTML 上。想排除的區塊用 data-pagefind-ignore 標記。想作為 filter 的屬性用 data-pagefind-filter="name:value"。

Default UI 的樣式是 Pagefind 自家風格

核心定義：PagefindUI component 有固定的視覺設計，透過 CSS variable 可微調顏色、圓角、spacing。

含義：想要與 theme 完全融合有兩條路 — 覆寫 CSS variable（官方 docs 列出可覆寫清單），或改用 Pagefind JS API 自己組 UI（更完整客製）。

Build pipeline 多一步

核心定義：Pagefind 是 Hugo build 外的獨立步驟。

含義：CI 與本地都要記得跑 npx pagefind。這個 blog 以 Makefile 的 make site 封裝 hugo + pagefind 兩步，把「記得」轉成 infrastructure 強制項。

適合的場景

• 靜態站、內容持續成長
• 部署在 GH Pages / Netlify / Cloudflare Pages 等純靜態平台
• 希望零外部依賴、完全自託管
• 內容以文字為主（blog、docs、knowledge base）
• 未來可能換 framework — 希望搜尋整合不隨之重寫

content/skills/ 收錄從 .claude/skills/ 轉成文章的 skill 版本。

同一份 skill 有兩種存在形式，各自負責不同角色：

兩處內容相同、結構略有差異：.claude/ 版本保留原始 SKILL.md + references/ 巢狀結構以配合 Claude 的路徑解析；content/ 版本扁平化（references 內容升級到同層），以契合 blog 的單層文章呈現。

目前收錄的 skill

把新 skill 轉成文章的標準流程

以下步驟假設新 skill 已經放在 .claude/skills/<name>/，包含 SKILL.md 和（可能的）references/ 子資料夾。

Step 1：複製一份到 content/skills/

1cp -R .claude/skills/<name> content/skills/<name>

Claude 版保持原樣、不再動它；所有後續修改都只改文章版。

Step 2：扁平化 references/

Blog 的文章層級為單層，不保留 references 子資料夾。把所有 reference 移到跟 SKILL.md 同一層：

1cd content/skills/<name>
2git mv references/*.md .
3git rm references/.gitkeep       # 如果有
4rmdir references

Step 3：把 SKILL.md 改成小寫 skill.md

Hugo pretty URL 會把檔名小寫輸出（SKILL.md → /skills/<name>/skill/），但 mdtools cards 連結檢查以檔名大小寫敏感的方式解析 URL 回檔案位置。若檔案是 SKILL.md，cards 嘗試開啟 skill.md 找不到，就會報 L1-broken-link。

避免這個陷阱，把 content 版本的檔名直接改成小寫：

1git mv content/skills/<name>/SKILL.md content/skills/<name>/skill.md

.claude/ 版保留原本的 SKILL.md（符合 Claude skill 慣例）。兩邊檔名不同是刻意的：runtime 讀 .claude/SKILL.md、Hugo 渲染 content/skill.md、cards check 能解析。

Step 4：修改 skill.md 的內部連結

skill.md 裡原本的 references/X.md 引用要改。有兩種合法寫法擇一：

• Markdown 相對路徑：./X.md — 最無痛，Hugo render hook 會自動解析到對應頁面
• Hugo content-root 絕對路徑：/skills/<name>/<slug>/ — 最穩，跟 blog 其他文章遷移後的寫法一致

批次替換範例（將 references/ 前綴整串刪除）：

1sed -i '' 's|references/|./|g' content/skills/<name>/skill.md

記得同時更新 ## Directory Index 區塊那張 ASCII tree — 刪掉 └── references/ 那一層、所有 reference 檔案縮排提到 skill.md 同層。

Step 5：建立 _index.md（section 索引）

content/skills/<name>/_index.md 是 Hugo section 的 landing page，URL 是 /skills/<name>/。

必備欄位（Hugo + mdtools 要求）：

1---
2title: "<Skill 名稱中英對照>"
3date: <YYYY-MM-DD>
4description: "<一句話描述 skill 做什麼>"
5tags: [...]
6---

內容建議包含：

1. 簡述：這個 skill 是什麼、解決什麼問題
2. 閱讀順序：場景 1（第一次接觸）與場景 2（已熟悉、直接解決任務）兩個切入點
3. 觸發路由表：複製 SKILL.md 的「When to Consult This Skill」表，但把檔案路徑替換成 Hugo 絕對 URL（/skills/<name>/<slug>/）
4. 與 blog 其他資料的關係：對照表（.claude/skills/<name>/、相關 content/posts/...）
5. Last Updated：同步日期與 .claude/ 版 SKILL.md 的 version

可參考 compositional-writing 的 _index.md 當範本。

Step 6：補 Hugo frontmatter 到 skill.md 與每份 reference

原始 skill.md 與 reference 的 frontmatter 是為 Claude runtime 設計的（欄位多為 name/license/metadata），Hugo 與 mdtools 需要的是 title + date。每份檔案：

1. 把原 frontmatter 保留或替換成 Hugo 規格（title、date、description、tags）
2. 刪掉 body 開頭的 # H1（Hugo 會從 title 自動生成 H1，保留會觸發 MD025-no-body-h1）

Step 7：跑 make check 與 hugo 驗收

1make check    # fmt + lint + cards，三個閘門全綠
2hugo          # 確認無 WARN/ERROR，page count 多了對應檔數

幾個常見訊號與對應的修補點：

Step 8：更新本 content/skills/_index.md 的「目前收錄」表

把新 skill 加入上方的表格，含主題一句話與 Hugo URL。

Step 9：commit

單一 commit 收尾：

1git add .claude/skills/<name> content/skills/<name> content/skills/_index.md
2git commit -m "docs(skills): import <name> skill"

設計決策備忘

為什麼 .claude/ 保留 references/、content/ 扁平？

.claude/ 是 Claude runtime 的 SKILL 執行環境，SKILL.md 的路徑解析（references/X.md）是 skill 原生協議的一部分 — 改了會破壞 Claude 讀取行為。

content/ 是 blog 文章，Hugo 的 pretty URL 傾向單層結構（/skills/name/page/ 比 /skills/name/references/page/ 乾淨）。扁平化也讓 render hook 的 tooltip 與 mdtools 的 card graph 不必穿一層目錄。

兩種結構並行、各自最佳化、用 step 1 的複製動作維持同步。

為什麼不直接 symlink content/skills/ → .claude/skills/？

Symlink 會讓兩邊共用 frontmatter 與路徑規範。.claude/ 版的 frontmatter 是 skill protocol（name/license/metadata），與 Hugo 要的（title/date）相衝；body 開頭的 # H1 是 Claude 讀者的 context signpost，但在 Hugo 會跟 title 生的 H1 重複。結構上看似省事，語意上兩邊是不同受眾的產出，應該允許各自演化。

Last Updated

2026-04-24 — 初版：compositional-writing 轉文章完成，記錄標準流程。

最初的問題很小：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