vscode 本身不生成 markdown 目录，必须依赖插件如 markdown all in one；命令无响应需确认语言模式为 markdown、插件已启用、光标在有效区域；中文跳转失效应设 slugifymode 为 github；updateonsave 仅更新已有目录块，首次须手动执行命令；侧边栏大纲需开启 explorer.experimental.showoutline 和 outline.automaticcollapse 为 false。
VSCode 本身不生成 Markdown 目录，必须靠插件；但装错或配错，反而导致链接失效、跳转错位、更新不触发——核心问题不在“有没有”，而在“怎么用对”。
Markdown All in One 的 Create Table of Contents 命令为什么没反应？
常见现象：按下 Ctrl+Shift+P 输入命令后无响应，或插入空列表、只生成一级标题。
- 确认当前文件是
.md后缀，且未被 VSCode 识别为其他语言（右下角语言模式应为 “Markdown”） - 检查是否在纯文本区域执行命令——光标必须落在 Markdown 内容区，不能在代码块、HTML 标签内或 YAML front matter 中
- 插件可能被禁用：打开扩展面板，搜索
Markdown All in One，确保状态为“已启用”（不是灰色“已禁用”） - 部分工作区会禁用推荐插件：检查
.vscode/extensions.json是否遗漏该插件，或用户设置中extensions.ignoreRecommendations为true
生成的目录链接点不动？锚点 ID 和 GitHub 渲染不一致
典型表现：点击目录项跳转失败，或在 GitHub 上显示为 #undefined、#-1 等无效片段。
- VSCode 默认使用简化 ID 规则：中文标题会转成小写拼音+数字去重，空格/标点全删，比如
## 第一章：入门指南→#第一章入门指南；但 GitHub 使用更严格的 slug 化（如转成#第一章入门指南-1） - 解决办法：在
settings.json中加配置强制兼容"markdown.extension.toc.slugify": true，并启用"markdown.extension.toc.slugifyMode": "github" - 注意：若文档含重复标题（如多个
## 注意事项），VSCode 不自动加序号，需手动改标题或依赖插件的toc.slugifyMode行为
目录不随标题修改自动更新？别信“实时”二字
几乎所有插件都不真正“实时”监听——它们只在保存文件或手动触发时刷新，且默认关闭自动重生成。
- 手动更新最稳：改完标题后，再次运行
Create Table of Contents或Update TOC（不同插件命令名不同） - 想省一步？开启自动更新需额外配置：
"markdown.extension.toc.updateOnSave": true（仅Markdown All in One支持） - 但要注意：自动更新只扫描当前文件，不会跨文件同步引用；如果目录里引用了其他
.md文件的标题，它完全不管 - 某些插件（如
Auto Markdown TOC）要求你在文档中显式写[TOC]占位符，否则不识别更新位置
多级标题深度控制不当，目录又长又乱
默认会抓取 # 到 ###### 全部六级，但实际文档常只需 H2–H4，多余层级反而干扰阅读。
- 通过设置限制范围：
"markdown.extension.toc.levels": "2..4"（注意是字符串，不是数组） - 若想跳过某类标题（如所有
### 调试说明），可用"markdown.extension.toc.include"配正则，但多数插件不支持；更可靠的是加注释标记：<!-- omit in toc -->放在标题前一行 - 列表格式也影响可读性：
"markdown.extension.toc.unorderedList": false可切为有序列表，适合教程类文档；但 GitHub 不渲染有序 TOC 的编号，仅本地预览有效
最易被忽略的一点：目录生成依赖标题的语法正确性。哪怕多一个空格、少一个 #、或混用 === / --- 这类 Setext 式标题，插件就可能漏掉——它只认 ATX 语法（即 # 标题 形式）。写完标题先看右下角预览是否渲染成功，再生成目录，比事后调试快得多。
