前言¶

写长文档时，手动维护目录（TOC）很容易遗漏或错位，尤其是需要频繁插入或删除章节时。为了减少这类重复劳动，下面介绍一个能自动为 Markdown 文档生成目录的工具。

是什么¶

markdown-toc 是一个面向 Markdown 文档的目录生成工具，由用户 user_15292d5a 在 SkillHub 上发布，版本为 1.0.0。它通过解析 Markdown 文件中的标题，自动生成并插入对应的目录结构，适合在编写技术文档、笔记或报告时使用。

核心功能¶

• 解析 Markdown 文件中的标题（# 到 ######）。
• 自动生成目录列表，包含对应的锚点链接。
• 将目录插入到指定位置，通常放在文档开头。

安装与启用¶

markdown-toc 提供以下安装方式（以官方文档为准）：

npm install -g markdown-toc

安装完成后，可通过命令行使用：

markdown-toc -i README.md

其中 -i 表示在文件内插入目录。若需要将目录写入到指定位置，可在配置或命令中指定输出路径。

典型用法¶

1. 在终端中进入存放 Markdown 文件的目录。
2. 运行安装命令（见上文）。
3. 对目标文件执行目录生成命令，目录会自动插入到文档开头。

适用场景与注意¶

• 适合需要频繁更新目录的技术文档、API 文档或项目 README。
• 需要提前安装 Node.js 环境。
• 生成的目录会覆盖文件中原有的 TOC 内容，建议先备份。

总结¶

markdown-toc 通过自动化目录生成，减少了手动维护的出错概率，让文档结构更易维护。如需了解更多，可访问官方地址：https://api.skillhub.cn/user_15292d5a/yjkj-markdown-toc