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

本 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 實作保持同步。

這篇文章記錄了我從零開始建立 Hugo 部落格並安裝 Bear Cub 主題的完整過程，包含常見的設定問題和解決方案。

為什麼選擇 Hugo ？

特點：Go 語言寫的，速度極快

優點

生成速度最快（

單一 binary → 不需要安裝 Node/Ruby 環境，跨平台好用

主題多

部署方便（build → 靜態檔 → push）

缺點

需要本地 build，再 push 結果到 GitHub Pages（不像 Jekyll 原生）

模板語法（Go Template）對新手稍有難度

Plugin 擴展性不如 Node.js 生態

基本安裝與設定

1. 初始化 Hugo 專案

1# 在現有的 GitHub 專案中初始化 Hugo
2hugo new site . --force

2. 安裝 Bear Cub 主題

1# 使用 git submodule 安裝（推薦）
2git submodule add https://github.com/clente/hugo-bearcub.git themes/hugo-bearcub

3. 基本設定檔案 (hugo.toml)

 1# 基本設定
 2baseURL = 'https://你的用戶名.github.io/blog'
 3theme = 'hugo-bearcub'
 4copyright = '你的名字 (CC BY 4.0)'
 5defaultContentLanguage = 'zh-tw'
 6
 7# 產生 robots.txt 以利於 SEO
 8enableRobotsTXT = true
 9
10# 設定語法高亮
11[markup]
12  [markup.highlight]
13    lineNos = true
14    lineNumbersInTable = false
15    noClasses = false
16  [markup.goldmark]
17    [markup.goldmark.renderer]
18      unsafe = true
19
20# 多語言模式設定
21[languages]
22  [languages.zh-tw]
23    title = '我的部落格'
24    languageName = 'zh-TW 🇹🇼'
25    LanguageCode = 'zh-TW'
26    contentDir = 'content'
27    [languages.zh-tw.params]
28      madeWith = '使用 [Bear Cub](https://github.com/clente/hugo-bearcub) 製作'
29
30[params]
31  # 網站描述
32  description = '我的個人部落格，分享技術與生活'
33  
34  # 網站標題
35  title = '我的部落格'
36  
37  # 日期格式
38  dateFormat = '2006-01-02'
39  
40  # 主題樣式 (original 或 herman)
41  themeStyle = 'original'
42  
43  # 自動產生社群媒體卡片
44  generateSocialCard = true
45  
46  # 作者資訊
47  [params.author]
48    name = '你的名字'
49    email = 'your.email@example.com'

首頁內容自訂

建立首頁內容檔案

在 content/_index.md 建立檔案：

 1---
 2title: "首頁"
 3---
 4
 5# 歡迎來到我的個人部落格
 6
 7嗨！我是 **你的名字**，歡迎來到我的數位天地。
 8
 9## 關於這個部落格
10
11這裡是我分享想法、學習心得和生活點滴的地方。你可以在這裡找到：
12
13- **技術文章**：程式開發經驗分享
14- **學習筆記**：新技術的學習過程
15- **專案記錄**：有趣的專案開發歷程
16- **生活感悟**：日常生活的思考與體驗
17
18## 最新文章
19
20歡迎查看我的[最新文章](/posts/)，或者透過[標籤](/tags/)來瀏覽特定主題的內容。
21
22## 聯絡我
23
24如果你想要與我交流或合作，歡迎透過以下方式聯絡：
25
26- Email: your.email@example.com
27- 有任何問題或建議，也歡迎在文章下方留言
28
29---
30
31*感謝你的造訪，希望這些內容對你有所幫助！*

建立文章

快速建立新文章

1# 建立新文章
2hugo new content posts/文章標題.md

文章格式範例

 1---
 2title: "文章標題"
 3date: 2025-08-22T20:41:50+08:00
 4draft: false
 5description: "文章描述，用於 SEO 和社群分享"
 6tags: ["標籤1", "標籤2"]
 7---
 8
 9文章內容寫在這裡...
10
11## 小節標題
12
13- 列表項目
14- 另一個項目
15
16### 程式碼範例
17\`\`\`bash
18echo "Hello Hugo!"
19\`\`\`

文章摘要與繼續閱讀設定

摘要顯示功能

為了避免文章列表頁面顯示完整內容，我們可以設定文章摘要功能，讓列表只顯示文章摘要並提供「繼續閱讀」按鈕。

1. 自動摘要設定

在 hugo.toml 中設定摘要長度：

1# 摘要設定
2summaryLength = 200  # 摘要字數限制

說明

• 當文章沒有手動設定摘要時，Hugo 會自動截取前 200 個字元
• 對於中文內容，200 個字元大約是 100-150 個中文字
• 對於英文內容，200 個字元大約是 30-40 個英文單詞

2. 手動摘要設定

方法一：使用 <!--more--> 標記

在文章中插入 <!--more--> 來精確控制摘要位置：

 1---
 2title: "文章標題"
 3date: 2025-01-XX
 4tags: ["標籤1", "標籤2"]
 5---
 6
 7這是文章的開頭部分，會顯示在列表中。
 8
 9這裡是更多內容...
10
11<!--more-->
12
13這裡是文章的其餘部分，只會在單篇文章頁面中顯示。

方法二：使用 description 參數

在文章的 front matter 中設定 description：

1---
2title: "文章標題"
3date: 2025-01-XX
4description: "這是文章的摘要，會顯示在列表中"
5tags: ["標籤1", "標籤2"]
6---
7
8文章內容...

3. 摘要優先順序

Hugo 的摘要顯示優先順序：

1. <!--more--> 標記 - 最高優先級
2. description 參數 - 第二優先級
3. 自動截取 - 使用 summaryLength 設定

4. 列表頁面樣式

設定完成後，文章列表會以卡片式設計顯示：

• 文章標題：可點擊進入完整文章
• 發布日期：顯示在標題旁邊
• 文章摘要：只顯示摘要內容
• 繼續閱讀按鈕：當文章被截斷時顯示
• 標籤：顯示文章相關標籤

GitHub Actions 自動部署

設定工作流程

在 .github/workflows/hugo.yml 建立自動部署設定：

 1name: Deploy Hugo site to GitHub Pages
 2
 3on:
 4  push:
 5    branches: ["main"]
 6  workflow_dispatch:
 7
 8permissions:
 9  contents: read
10  pages: write
11  id-token: write
12
13jobs:
14  deploy:
15    runs-on: ubuntu-latest
16    steps:
17      - uses: actions/checkout@v4
18        with:
19          submodules: recursive
20      
21      - name: Setup Hugo
22        uses: peaceiris/actions-hugo@v2
23        with:
24          hugo-version: 'latest'
25          
26      - name: Build
27        run: hugo --minify
28        
29      - name: Deploy to GitHub Pages
30        uses: peaceiris/actions-gh-pages@v3
31        with:
32          github_token: ${{ secrets.GITHUB_TOKEN }}
33          publish_dir: ./public

常見問題與解決方案

社群媒體預覽卡片顯示亂碼問題

當你在 Discord、Facebook 等社群媒體分享文章時，如果預覽卡片中的中文顯示為問號（？），這是因為預設字型不支援中文字符。

問題表現

• 分享連結時，預覽卡片的標題顯示為問號
• 作者名稱顯示為 map[name:作者名稱] 而不是純文字

解決方案

1. 建立客製化的社群媒體卡片檔案

首先，在你的專案根目錄建立目錄並複製檔案：

1# 建立 layouts/partials 目錄
2mkdir -p layouts/partials
3
4# 複製主題的 social_card.html 到你的專案中
5cp themes/hugo-bearcub/layouts/partials/social_card.html layouts/partials/

2. 修改字型設定

編輯 layouts/partials/social_card.html 檔案（注意這是你專案中的檔案，不是主題檔案）：

1<!-- 將第 2 行的字型 URL 替換為支援中文的字型 -->
2{{ $font := resources.GetRemote "https://github.com/adobe-fonts/source-han-sans/raw/release/OTF/TraditionalChinese/SourceHanSansTC-Bold.otf" }}

3. 修正作者名稱顯示

在同一個檔案中，找到第 27 行並修改：

1<!-- 原來的程式碼 -->
2{{ $author := (default $.Site.Params.author.name ($.Param "author") ) }}
3
4<!-- 修改為 -->
5{{ $author := (or ($.Param "author") $.Site.Params.author.name) }}

重要說明：我們將檔案複製到專案的 layouts/partials/ 目錄而不是直接修改主題檔案，這樣做的好處是：

• 保持主題的 git submodule 乾淨
• 未來更新主題時不會遺失客製化設定
• Hugo 會優先使用專案中的檔案覆蓋主題檔案

4. 確保社群媒體卡片功能開啟

在 hugo.toml 中確認設定：

1[params]
2  # 自動產生社群媒體卡片
3  generateSocialCard = true

字型選擇說明

• Source Han Sans TC：Adobe 思源黑體繁體中文版本，支援完整中文字符集
• 替代方案：也可以使用 Google 的 Noto Sans CJK 字型
• 檔案大小：中文字型檔案較大，但現代瀏覽器會快取字型檔案

修改完成後，重新建立並部署網站，社群媒體預覽就會正確顯示中文內容了。

實用技巧與其他設定

本地開發

1# 啟動開發伺服器
2hugo server
3
4# 包含草稿
5hugo server --buildDrafts
6
7# 指定 IP 和 Port
8hugo server --bind 0.0.0.0 --port 1313

不同電腦上的工作流程

主要開發電腦

• 安裝 Hugo 進行完整開發
• 可以本地預覽和測試

其他電腦/緊急更新

• 只需要 Git 和文字編輯器
• 直接編輯 Markdown 檔案推送即可
• GitHub Actions 會自動編譯和部署

常見檔案位置

• 設定檔：hugo.toml
• 首頁內容：content/_index.md
• 文章：content/posts/
• 主題：themes/hugo-bearcub/
• 靜態檔案：static/

總結

透過這個設定流程，我們成功建立了：

• 快速載入的靜態部落格
• 支援繁體中文的介面
• 自動化的 GitHub Pages 部署

現在你可以專注於寫作，讓 Hugo 和 GitHub Actions 處理其他的技術細節！

這篇教學記錄了我的實際設定過程，希望對其他想要建立 Hugo 部落格的朋友有所幫助。