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

 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}

 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       # 跨文件檢查，失敗即阻擋

1make check

 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

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