Markdown 目錄（TOC）產生器

完整範例：標題進去，目錄出來

以下是一份簡短的手冊，有一個第一層大標題、數個第二層章節、若干第三層小節，還藏了一個第四層標題：

# Deploy Handbook

Everything the team needs before shipping.

## Getting started

### Install the CLI

### Options

## Continuous delivery

### Options

#### Retry policy

## FAQ: what breaks & why

把最小層級設為 2、最大層級設為 3，產生器會輸出：

- [Getting started](#getting-started)
  - [Install the CLI](#install-the-cli)
  - [Options](#options)
- [Continuous delivery](#continuous-delivery)
  - [Options](#options-1)
- [FAQ: what breaks & why](#faq-what-breaks--why)

短短六行，裡面看得到四個判斷。

輸出裡的四個判斷

• 大標題消失了。# Deploy Handbook 比最小層級還淺，因此被排除。
• 最深的標題也不見了。#### Retry policy 超過最大層級。
• 第二個 Options 指向 #options-1。同一頁的錨點 ID 必須唯一，重複時就依序編號。
• & 符號留下了 --。最後那個錨點看起來像打錯字，其實完全正確。

從貼上到發佈的完整步驟

1. 把文件貼進本頁最上方的輸入框。
2. 把最小層級設為 2，讓文件大標題退出清單。
3. 把最大層級設為 3；文件很短的話設 4 也可以。
4. 複製清單，貼到檔案前面的 ## 目錄 標題底下。
5. 發佈後點一個項目，確認網址列跟錨點對得上。

為什麼每一項都只是普通連結

每個項目都只是一般的 Markdown 連結，只是目標從網址換成片段識別碼。機制就這麼簡單：[文字](#錨點) 會跳到同一份檔案中 ID 為該錨點的標題。這裡完全沒有平台專屬的東西，所以文件搬到別處之後，只要新的渲染器用同樣方式產生 ID，目錄照樣能用。

GitHub 如何把標題變成錨點 ID

連結目標不是你自己發明的，而是由標題文字經過一組固定規則推導出來。知道這組規則，你光用眼睛就能看出哪個連結會壞掉。

四條規則，依序套用

1. 全部轉成小寫。
2. 刪掉所有不是字母、數字、空白、連字號或底線的字元。
3. 把剩下的每個空白換成連字號。
4. 如果這一頁已經用過同樣的 ID，就依出現順序加上 -1、-2。

真實標題與它們產生的錨點

寫成文字聽起來很單純，但第二條規則不斷讓人踩雷，因為標點是被「刪掉」而不是被「取代」。實際的轉換結果如下：

哪些渲染器遵守同一套規則

GitLab、Gitea、Docusaurus 與多數靜態網站產生器都跟得夠近，產生出來的目錄可以直接沿用。Bitbucket 與部分較舊的 wiki 則不同，也有少數渲染器會在每個 ID 前面加上 user-content- 之類的前綴。標題的完整說明請見 Markdown 完整指南，這套行為所屬的方言則由 GitHub 風格 Markdown 負責解釋。

注意：標點很多的標題，千萬不要用猜的。先發佈頁面、點一次連結，直接從網址列把 ID 讀回來。花兩秒，勝過一個點了沒反應的連結。

GitHub 已經會自動產生目錄，那還需要這個嗎？

先把話說清楚：在 GitHub 上，手動維護的目錄如今大致上是多餘的。每份渲染後的 Markdown 檔案，檔頭都有一顆目錄按鈕，點下去會展開依標題整理的大綱；因為是在瀏覽當下即時產生，它永遠與內容同步。

那顆按鈕照顧不到的五個場景

它只涵蓋一個場景，但 Markdown 檔案落腳的地方很多，所以花四秒產生一份清單仍然值得：

• 其他代管平台。自架的 GitLab、Gitea、Codeberg 與公司內部 wiki 支援程度不一，有些根本沒有這項功能。
• 靜態網站。部分 Hugo、Jekyll、Astro 主題會在側邊欄顯示大綱，但更多主題不會；寫在檔案裡的清單則不挑主題。
• 倉庫之外的長文件。規格書或維運手冊，在編輯器、Obsidian 或 Markdown 檢視器裡閱讀時，並沒有那顆檔頭按鈕可以按。
• 轉換後的輸出。檔案變成 HTML 或存成 PDF 時，寫在內文裡的目錄會被一起帶走，介面功能則不會。
• 直接讀原始檔。在終端機或 diff 裡打開 .md 的人，第一眼就能看見整份文件的結構。

一條可以照著用的原則

只放在 GitHub 上的短篇 README，就別做手動目錄。超過約一千字，或會被拿到別處閱讀的文件，就產生一份。之後每次新增或改名章節時重新產生即可，成本就是貼一次。

常見問題與修法

目錄壞掉的方式其實不多，而且症狀會直接告訴你是哪一種。

點了連結沒有反應

錨點與標題對不上。原因通常出在標點：有人手寫連結時，保留了 ID 規則會刪掉的字元。

<!-- 壞掉：冒號與大寫字母都被保留了 -->
- [FAQ: Setup](#FAQ:-Setup)

<!-- 正確 -->
- [FAQ: Setup](#faq-setup)

兩個連結跳到同一個位置是它的親戚。兩個標題文字相同，後者需要 -1 後綴。重新產生就能修好，但更好的做法是替其中一個改名：有兩個「Options」章節的文件，不論連結多正確都很難導覽。

清單裡少了某個標題

依序檢查三件事：

• 它是不是落在程式碼區塊裡？那裡的 # 只是註解，不是標題。
• 它是不是 Setext 樣式的標題？也就是用 === 或 --- 在文字下方畫底線，而不是用井字號。
• 井字號後面是不是漏了空白？多數解析器裡 ##Setup 只是普通文字，## Setup 才是標題。

縮排層級看起來很怪

縮排完全對應檔案裡的標題層級。第二層章節後面直接接第四層標題，清單就會一次縮兩格。該修的是文件而不是目錄，因為跳過標題層級同樣會讓螢幕閱讀器與搜尋引擎困惑。清單指南有完整的巢狀規則。

目錄脫節，或搬家之後整份失效

脫節是手動清單真正的代價，解法是重新產生而不是手工補丁：把現在的文件貼進來、複製新清單、覆蓋舊的那一份。目的地渲染器用不同規則產生 ID，則是同一個問題的加強版，所有連結會一次失效，所以先在目的地點一個連結測試再信任整份清單；需要手改某一項時，語法速查表放在旁邊很方便。文件裡若還有從試算表搬來的表格，那部分交給表格轉 Markdown 工具。