Ctrl+Shift+P执行Create Table of Contents是唯一可靠入口；目录生成依赖插件，需手动触发、配置toc.levels、用HTML注释跳过标题，且不自动同步变更。
Ctrl+Shift+P 执行 Create Table of Contents 是唯一可靠入口
VSCode 原生不支持目录自动生成，所有“一键生成”行为都依赖插件注册的命令。即使装了 Markdown All in One，也**不能**靠快捷键直接触发（比如没有全局绑定的 Ctrl+T 这类），必须走命令面板。常见错误是反复按 Ctrl+B 或 Alt+C 试图“碰巧”生成——这些是格式化快捷键，和目录无关。
实操建议：
- 光标先定位到你想插入目录的位置（通常是文档顶部或
## 目录标题下方） - 务必用
Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS）打开命令面板 - 输入完整命令名
Create Table of Contents，别缩写成 “toc” 或 “table”，部分版本对模糊匹配不敏感 - 执行后，目录会以无序列表形式插入，锚点自动基于标题文本生成（如
## 环境准备→#环境准备）
toc.levels 配置决定生成几级标题，不是靠 Markdown 语法本身
很多人误以为只要写 ###### 就能进目录，其实默认只包含 # 到 ###（即 H1–H3）。超出层级的标题不会出现在生成的目录里，哪怕它们语法完全正确。
实操建议：
- 在 VSCode 设置中搜索
toc.levels，修改为"markdown.extension.toc.levels": "2-5"可包含 H2 到 H5 - 注意格式是字符串，不是数字数组；
"1-6"表示全部层级，但实际渲染深度受预览器限制 - 中文标题会被转为 URL 编码（如
环境准备→%E7%8E%AF%E5%A2%83%E5%87%86%E5%A4%87），GitHub 渲染兼容，但本地点击跳转可能失败——这不是 bug，是 VSCode 预览器的已知限制
<!-- omit from toc --> 注释才是跳过特定标题的正解
想让某个 ## 标题不出现在目录里？删掉它、改成段落、或加 ~~~ 都不行。唯一有效方式是紧贴标题上方加 HTML 注释。
实操建议：
- 注释必须**紧邻标题前一行**，且独占一行：
<!-- omit from toc --><br>## 这个标题不会进目录
- 不能写成
<!--omit from toc-->（少空格）或<!-- omit from toc --> ## 标题（在同一行） - 该注释只影响当前标题，不影响后续层级；如果想跳过整个二级章节下的所有子项，需在每个子标题前都加一遍
- 插件不识别其他注释格式（如
[comment]: # (omit)），只认这个固定字符串
保存时自动更新目录 ≠ 实时同步，改标题后必须手动再生
即使设置了 "markdown.extension.toc.updateOnSave": true，它只在保存文件时重新扫描并覆盖原有目录内容——前提是目录区块本身没被手动编辑过。一旦你删掉某行、改了链接文字、或加了额外缩进，插件就放弃接管，下次保存也不会动它。
实操建议：
- 把目录块当作“只读区域”：不要在里面增删
-、改括号里的文字、调整缩进 - 标题文本变更后，旧锚点失效，点击跳转会 404；此时必须删掉整个目录块，再执行一次
Create Table of Contents - 多人协作时，建议在 PR 描述里注明“本次提交含标题结构调整，请同步 regenerate TOC”，避免遗漏
目录生成逻辑简单，但锚点映射、层级裁剪、注释识别这些细节全靠插件实现，不是 Markdown 规范本身的能力。最容易被忽略的是：目录不是“活”的导航组件，它只是快照式静态链接列表——你得主动刷新，而不是期待它像网页侧边栏那样自动响应滚动。
