Markdown目录自动生成工具：为文档添加导航的最简单方式

写一篇很长的README文件时，你总会在某个时刻意识到需要目录。然后你开始手动将标题文本转为小写，把空格替换成连字符，去掉特殊字符，一个个地制作锚点链接。之后标题改了，链接要更新；新章节加了，目录也要跟着改……目录维护本身变成了一个负担。

这整个过程其实完全是机械性的。GitHub-Flavored Markdown的锚点ID生成算法是确定的、有据可查的，完全不需要人工操作。Markdown目录生成器可以自动化这一切。粘贴你的Markdown文档，立即得到正确缩进、链接准确的目录，直接复制粘贴到文档里就好了。

为什么目录很重要

目录不是装饰。在较长的文档中，目录让读者一眼看清文档的整体结构，并能直接跳转到感兴趣的章节。

在GitHub README中，这一点尤为重要。第一次访问代码仓库的开发者会快速浏览README。如果内容很长却没有目录，理解项目结构就需要额外的时间。一个清晰的目录能立刻传达出【这是这个项目的结构】这样的信息。

技术文档也是如此。API参考、架构指南、入职文档——读者几乎不会从头读到尾，而是寻找他们需要的具体内容。目录就是引路的地图。

锚点ID生成算法详解

GitHub从标题文本生成锚点ID的方式很简单：

删除所有HTML标签
将文本全部转为小写
删除除连字符和空格外的所有标点符号
将空格替换为连字符
去重处理：如果相同标题出现多次，依次追加 -1、-2 等

例如，## API参考（v2）会变成 #api参考v2。## 快速开始 会变成 #快速开始。

中文标题的情况：中文字符会原样保留在锚点ID中。虽然URL中会显示百分比编码（如 %E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B），但浏览器和GitHub都能正确处理。

GitHub与GitLab的差异

GitHub和GitLab遵循相同的基本算法，但对某些字符的处理方式略有不同。对于普通的中文文档，两者结果几乎相同。差异主要出现在：

括号和某些标点：GitHub会删除，GitLab有时处理方式不同
标题中含有emoji：两个平台的行为都不一致

如果你的文档需要在两个平台上发布，建议保持标题文本简洁——少用特殊标点。

实际示例

假设有这样的文档结构：

# 我的库

## 安装

### macOS

### Linux

## 快速开始

## API参考

### 配置选项

### 方法

## 参与贡献

## 许可证

通过生成器产生的目录：

## 目录

- [安装](#安装)
  - [macOS](#macos)
  - [Linux](#linux)
- [快速开始](#快速开始)
- [API参考](#api参考)
  - [配置选项](#配置选项)
  - [方法](#方法)
- [参与贡献](#参与贡献)
- [许可证](#许可证)

注意几点：# 我的库 这个H1标题被排除在目录之外，因为H1是文档标题而非导航目标。层级结构也被完整保留——H2在最顶层，H3缩进一级。

特殊字符和边界情况

坦率地说，某些情况需要特别注意。

标题中含有emoji — 类似 ## 🚀 快速开始 的标题，不同渲染器对emoji的处理方式可能不同。建议在实际平台上验证含emoji标题的锚点链接是否正确。

标题中含有代码段 — 类似 ## `render()` 函数的情况，反引号会被删除，生成 #render-函数。这通常是期望的结果。

括号或特殊字符 — ## API参考（v2） 中的括号会被删除，生成 #api参考v2。功能上没问题，但如果有多个类似名称的章节，锚点可能会有意想不到的形式。

集成到工作流程

典型的使用流程如下：

先写文档内容（不必担心目录）
结构基本确定后，将Markdown粘贴到目录生成器
复制生成的目录
粘贴到文档顶部（介绍段落之后）

保持同步

这个工具的局限性在于文档修改后目录不会自动更新。添加或修改标题后，需要重新生成并替换目录。

对于小型项目，这不是大问题。但对于频繁更新的大型文档，可以考虑自动化工具：

doctoc：npm包，设置为pre-commit钩子后提交时自动更新目录
VS Code插件：多个Markdown TOC相关插件支持保存时自动更新
GitHub Actions：配置工作流在推送时运行doctoc

目录生成器最适合一次性生成，或者想在提交之前确认输出效果的场景。

搭配使用的相关工具

以下工具与Markdown目录生成配合使用效果很好：

Markdown预览工具可以实时渲染你的Markdown文档，让你在复制目录到仓库之前直观确认效果，避免格式问题出现在正式发布的文件中。

Markdown转HTML转换器适用于需要将包含目录的文档转为HTML的场景——例如粘贴到只接受HTML的CMS，或者从Markdown内容创建邮件模板。

Markdown表格生成器专门用于生成手动编写极为繁琐的管道分隔表格语法。如果文档中包含数据表格，这个工具能节省大量时间。

实际使用中的小技巧

先整理好标题层级结构。 如果H2和H3混乱交错没有清晰的结构，生成的目录也会同样混乱。目录生成的过程有时能暴露出文档结构上你之前没有注意到的问题。

扁平结构也完全没问题。 只有H2标题的文档会生成一个没有缩进的简单列表目录，这往往更加简洁明了。不要为了让目录看起来更丰富而添加不必要的H3。

考虑读者的阅读方式。 开发者会反复查阅的API参考文档适合详细的多层级目录。第一次阅读的README则用只包含主要章节的简短目录就足够了。

将机械性的工作自动化，让你能专注于真正重要的内容创作。下次写文档时，试试Markdown目录生成器吧。