跳到主要内容

Markdown 目录怎么自动生成:按标题层级一键得到带锚点的 TOC

讲清楚 Markdown 目录的生成原理:标题怎么转成锚点、层级缩进怎么算、GitHub 的 slug 规则有哪些坑,以及给长文档和 README 加可点击 TOC 的稳妥做法。

发布于 作者 李雷
#Markdown #目录 #TOC #文档写作 #GitHub

Markdown 目录怎么自动生成:按标题层级一键得到带锚点的 TOC

写到几千行的 README 或者一份长规范文档,最先崩溃的不是内容,是导航。读者拉到一半找不到安装步骤,你自己改文档时也得满屏滚。Markdown 本身不带目录功能,所以一份能点的目录(TOC)得手动维护,而手动维护正是最容易出错的地方:标题改了,目录里的锚点还指着旧的,点过去就是 404。

这篇把目录自动生成这件事讲透:标题是怎么变成锚点的,层级缩进按什么算,以及各家平台的 slug 规则差在哪。看完你会明白为什么同一份目录贴到 GitHub 能点,贴到 Bitbucket 就失效。

目录的本质:标题列表加锚点链接

一份 Markdown 目录,说到底就是一组形如 - [标题](#锚点) 的链接。左边是显示文字,右边的 #锚点 指向文档里对应的那个标题。渲染器(GitHub、GitLab、各种文档站)在渲染每个标题时,会顺手给它生成一个 id,目录里的 #锚点 命中这个 id,点击就能跳过去。

所以生成目录只有两步:把所有标题按层级抽出来,再给每个标题算出它对应的锚点字符串。难点全在第二步,因为锚点不是标题原文,要经过一套转换规则。

标题怎么转成锚点:小写加连字符

以 GitHub 规则为例,一个标题转锚点的核心动作是这几条:全部转小写,空格换成连字符,大多数标点直接丢掉,下划线和 Unicode 字母数字保留。

举个具体的。标题 ## 安装与配置 (Setup) 在 GitHub 上的锚点是 #安装与配置-setup:中文照样保留,空格变连字符,括号被丢掉,Setup 转成小写。再比如 ### API_Key 说明,下划线保留,得到 #api_key-说明。

还有一个最容易踩的坑:重复标题。同一份文档里出现两次 ## Setup,第一次锚点是 #setup,第二次就成了 #setup-1,第三次 #setup-2,以此类推。锚点必须唯一,渲染器自动加后缀,目录也得跟着加,否则两个链接都指向第一个 Setup。这套去重规则我用过 Markdown 目录生成器,它是直接照 GitHub 原样实现的,不用自己数后缀。

层级缩进:按可见的最浅级别算

目录的嵌套缩进不是按标题的绝对级别硬排的,而是按这次实际选中的最浅级别算。这点很关键。

假设你的 README 只想收 H2 到 H4,文档大标题那个 H1 不进目录。如果按绝对级别,H2 就得先缩两层,排版会歪到右边一截。正确做法是:H2 当作最浅级别,顶头不缩进,H3 缩一级,H4 缩两级。这样选 H2–H4 也能得到一份齐头排版的大纲,看着才舒服。

缩进用 2 个空格还是 4 个空格,看团队习惯。GitHub 两种都认,有些老式渲染器对 4 空格更稳。

一个真实的输入输出例子

假设文档里有这么几个标题:

# 用户手册
## 快速开始
### 安装
### 第一次运行
## 进阶配置
## 常见问题

选 H2–H3、GitHub 风格、2 空格缩进,生成的目录就是:

- [快速开始](#快速开始)
  - [安装](#安装)
  - [第一次运行](#第一次运行)
- [进阶配置](#进阶配置)
- [常见问题](#常见问题)

H1 的「用户手册」被「最小级别」过滤掉了,H2 顶头排,H3 缩进一级。如果再打开层级编号,左边会变成 1.、1.1、1.2、2.、3.,计数器按父级自动归零,跟书的目录一样,适合需要在评论里引用「见 2.1」的规范文档。

GitHub 之外:各家锚点规则不一样

我自己第一次踩坑,是把一批文档从 GitHub 搬到 GitLab wiki,搬完发现一半页内链接点不动。查了半天才搞清楚:GitHub 会把下划线处理掉,GitLab 却原样保留。同一个 ## my_section,GitHub 锚点可能是 #my-section,GitLab 是 #my_section,差一个字符就 404。

Bitbucket 更特别,它的锚点要带 markdown-header- 前缀。所以一份在 GitHub 上完美的目录,直接复制到 Bitbucket,链接会无声失效,页面不报错,就是点了没反应。结论很简单:复制目录前先确认目标平台,把锚点风格切到对应平台再生成,别指望一份目录通吃所有渲染器。

还有一个细节值得提:代码块里的 #。教程里贴 shell 会话,# 构建镜像 这种注释行看起来跟 H1 标题一模一样。靠谱的生成器会追踪围栏代码块并整段跳过,只把真正的标题抽出来,否则你的目录里会混进一堆注释行。

把目录拼回文档,以及配套工具

光生成目录还不够,得把它放回文档。常见做法是在正文里放一对 <!-- TOC --> / <!-- /TOC --> 注释标记,目录就嵌在中间。下次加了新章节,重新生成,只替换两个标记之间那段,正文一个字节都不动,这样反复更新也不会乱。

如果你正在 Markdown 和 HTML 之间来回倒腾,比如把文档发布到网页,可以配合 Markdown 转 HTML 一起用;反过来从网页内容整理回 Markdown,则用 HTML 转 Markdown。需要在文档里插数据表格的话,Markdown 表格生成器 也能省去手敲竖线的功夫。这几个工具都是浏览器本地处理,文档不上传,贴内部规范也放心。

把目录这件事交给规则去算,你只管写内容。标题改了重新生成一遍,锚点永远对得上,长文档也就一直找得到路。

Made by Toolora · Updated 2026-06-13