Markdown 目录生成
按 GitHub 规则算锚点,粘进 README 就能跳
如何使用本工具
- 把整篇 Markdown 粘进左边,右边立刻出目录列表。
- 默认到 H3,标题层级深的话把最大级别调到 H4 或全部。
- 代码块里的 # 会被跳过,YAML front matter 也不会被误当标题。
- 锚点按 GitHub 规则生成,直接粘进 README 的标题下面就能点跳转。
- 下方表格列出每个标题的实际锚点,可以核对中文标题算出来是什么样。
常见问题
Q:为什么有的标题点不动?
A:多半是锚点对不上。GitHub 的规则是:转小写、删掉除字母数字空格连字符下划线以外的所有字符、空格逐个换成 -、重名加 -1。本工具按这条实现,但 GitLab、语雀、VuePress 的规则各自略有不同,跨平台时以下方表格里的实际锚点为准。
Q:中文标题的锚点是什么样的?
A:GitHub 会保留中文,比如「快速开始」的锚点是 #快速开始,不是拼音也不是编码。标点会被删掉,「配置项(可选)」变成 #配置项可选。链接里的中文浏览器会自动做百分号编码,手写时保持中文即可。
Q:代码块里的 # 为什么不会被当成标题?
A:因为工具会跟踪 ``` 和 ~~~ 围栏的状态,围栏内整段跳过。这也是手写目录最容易出错的地方——Markdown 解析器当然知道,但用正则一把梭就会把 shell 注释全抓出来。
Q:同名标题会怎样?
A:第二个同名标题的锚点会变成 #标题-1,第三个是 #标题-2,和 GitHub 行为一致。不过同名标题本身不是好习惯,读者从目录里看不出区别,建议改得具体一点。
Q:Setext 标题(下面画 === 或 ---)支持吗?
A:不支持,只识别 # 开头的 ATX 写法。Setext 写法有歧义——`---` 既可能是 H2 下划线,也可能是分隔线或 YAML 结束标记,正确解析需要上下文。现在主流规范都推荐 ATX,建议统一改过来。
Q:目录应该放在什么位置?
A:放在开头的简介之后、第一个二级标题之前,加一行 `## 目录` 或 `## Table of Contents` 更清楚。如果文档很长(超过 10 个二级标题),只在开头给一级和二级,细节交给正文内的锚点。