sublime text 默认不支持自动生成 markdown 目录树，需安装第三方插件 markdowntoc 并正确配置 slugify、base_level 等参数，同时确保标题格式规范、无隐藏字符。
Sublime 里没有原生命令生成 Markdown 目录树
别折腾菜单栏找“插入目录”——Sublime Text 默认根本不支持自动解析标题生成 ## 级目录树。你看到的“目录插件”全是第三方扩展，得手动装、配、调用，而且行为差异很大。
常见错误现象：Package Control: Install Package 搜 “toc” 装了就以为能用，结果按快捷键没反应，或只生成空列表；还有人把 MarkdownPreview 当成目录生成器，其实它只渲染，不生成。
使用场景很明确：你正在写一个长 .md 文件，有 5+ 个 ## 或 ### 标题，想快速生成锚点链接结构，贴在文档开头。
实操建议：
- 装
MarkdownTOC（作者：jonschlinkert），不是MarkdownToc或AutoTOC—— 名字差一个字母就可能失效 - 安装后重启 Sublime，再打开一个
.md文件，确保语法高亮是Markdown（右下角显示，不是Plain text） - 光标放在想插入目录的位置（通常是文件最顶部），按
Ctrl+Cmd+P（macOS）或Ctrl+Shift+P（Win/Linux），输入MarkdownTOC: Insert/Update回车 - 默认会生成带锚点的列表，如
- [简介](#%E7%AE%80%E4%BB%8B)，但中文链接需开启slugify选项，否则可能出错
为什么生成的目录链接点不开？
不是 Sublime 的问题，是 Markdown 渲染器和锚点规则不一致导致的。浏览器或预览插件对中文标题转义方式不同，MarkdownTOC 默认用 URI 编码（比如 %E7%AE%80%E4%BB%8B），但有些渲染器只认短横线格式（jian-jie）。
参数差异直接影响可用性：
-
"slugify": true→ 生成jian-jie类型 ID（推荐，兼容性好） -
"slugify_mode": "github"→ 严格匹配 GitHub 风格（去标点、小写、空格变短横线） -
"auto_reload": true→ 保存文件时自动更新目录（省事，但改标题后要记得保存） - 不配
"base_level"时，##会被当一级，###当二级；若想让###变成第一级，设"base_level": 3
配置路径：Preferences → Package Settings → MarkdownTOC → Settings，编辑 User 设置，不要动 Default。
用命令行生成更可控，但得配合 Python
如果你常要批量处理多个 .md 文件，或者需要定制层级、忽略某些标题（如 ## 参考文献），GUI 插件反而麻烦。这时候直接用 markdown-toc CLI 更稳。
性能与兼容性影响小，但依赖环境：
- 先装 Python 包：
pip install markdown-toc - 生成当前文件目录：
mdtoc README.md -o -（输出到终端）或mdtoc README.md -i（原地插入） - 支持过滤：
mdtoc README.md --exclude "参考|附录"（正则匹配标题文本） - 注意：CLI 默认不处理中文编码，Windows 下可能乱码，加
--encoding utf-8
这个方式绕过了 Sublime 的解析限制，直接读文件内容，所以对缩进、空行、特殊符号更宽容。
容易被忽略的细节：标题前后空白和 HTML 注释
很多人生成目录失败，根本原因不是插件没装对，而是标题行里藏了看不见的字符。
常见错误现象：## 介绍 （末尾三个空格）、## <!-- 忽略 --> 简介、甚至全角空格或零宽空格（U+200B）——这些都会让 MarkdownTOC 无法识别为有效标题。
实操建议：
- 打开
View → Show White Space，检查标题行末尾是否有空格或制表符 - 禁用所有其他 Markdown 插件（尤其是
MarkdownEditing的增强模式），它们有时会干扰标题解析逻辑 - 如果用了 HTML 注释嵌入标题，要么删掉，要么换用 Markdown 原生注释
[//]: # (说明)，后者不会破坏标题结构
目录生成这件事，表面是工具问题，实际是格式洁癖问题。多一个空格，少一个换行，都可能让整个树塌掉。
