markdowntoc插件必须准确拼写为“markdowntoc”（作者jonschlinkert），装错如“markdowntoc”将导致命令不可用、配置不显示；安装后需重启sublime text，文件类型须为markdown且含合法#标题；中文锚点需配置"slugify":true、"slugify_mode":"github"、"uri_encoding":false；目录层级由"base_level"控制，默认1即包含#标题；"auto_reload":true仅在保存时触发更新，且toc块须连续无空行。
MarkdownTOC 插件名必须拼写准确，不能少字母或换顺序
装错插件是生成失败最常见的原因。Package Control 里搜 toc 会出来一堆名字相近的包：MarkdownTOC、MarkdownToc、AutoTOC、Table of Contents——只有 MarkdownTOC（作者 jonschlinkert）能稳定支持中文 slugify 和自动更新。装错一个字母，比如 MarkdownToc，按快捷键完全没反应，配置项也根本不会出现。
安装后必须重启 Sublime Text，否则命令面板里搜不到 MarkdownTOC: Insert/Update。
- 确认已安装：打开
Preferences → Package Settings → MarkdownTOC，能看到菜单说明已生效 - 文件类型必须是 Markdown：右下角状态栏显示
Markdown，不是Plain text或Text - 文件需有合法标题：至少一行以
#开头，且前面无空格或其它字符（# 标题或1. # 标题都不识别）
中文标题链接点不开？关键是 slugify 和 uri_encoding 的组合设置
默认生成的链接像 [简介](#%E7%AE%80%E4%BB%8B)，浏览器能解码，但 GitHub、GitLab、Obsidian 等多数渲染器只认短横线格式 [简介](#jian-jie)。点不开不是插件 bug，是 ID 格式不匹配。
必须在 Preferences → Package Settings → MarkdownTOC → Settings – User 中显式配置：
{
"slugify": true,
"slugify_mode": "github",
"uri_encoding": false
}
-
"slugify": true启用中文转拼音+短横线（如## 数据处理流程→data-chuli-liu-cheng） -
"slugify_mode": "github"严格遵循 GitHub 的锚点规则：去标点、小写、空格/中文全转短横线 -
"uri_encoding": false关闭 URI 编码，避免生成%E5%BC%95%E8%A8%80类 ID，否则和slugify冲突
为什么只生成 ## 及以下，漏掉 # 一级标题？min_depth 和 base_level 不是一回事
Table of Contents 插件用 min_depth 控制最小包含层级；而 MarkdownTOC 用 base_level 重定义“一级”的起始位置。两者参数名不同、作用逻辑也不同，混用会失效。
想让 # 项目概述 出现在目录第一层，必须设：
{
"base_level": 1
}
-
"base_level": 1表示把#当作目录一级（默认值就是 1，一般不用改） -
"base_level": 2表示把##当作一级，###当二级——适合文档开头已有固定封面标题时 - 别和
min_depth搞混：min_depth是Table of Contents插件的参数，MarkdownTOC不识别它
自动更新目录不生效？检查 auto_reload 和保存动作是否触发
"auto_reload": true 的意思是“保存文件时自动刷新目录”，不是“实时监听编辑”。很多人改完标题就等着目录变，结果没反应——因为还没 Ctrl+S。
- 确保配置中启用了
"auto_reload": true（默认是false） - 修改标题后必须手动保存文件，插件才会重新解析并覆盖旧 TOC
- 如果目录被手动删过，
auto_reload不会重建，得再执行一次MarkdownTOC: Insert/Update - 更新范围仅限当前光标所在位置的 TOC 块，不会动其他段落
最易忽略的一点：TOC 必须是连续的 Markdown 列表块（以 - 或 1. 开头），中间不能插入空行或其它内容，否则 Update 会失败或只更新前半部分。
