最稳的触发方式是ctrl+shift+p后搜索“create table of contents”，该命令无视光标位置与目录是否存在，始终基于#至######标题重新生成；支持自动更新但仅限未被手动修改的标准目录块，中文标题默认转为小写拼音锚点。
Ctrl+Shift+P 之后搜 Create Table of Contents 是最稳的触发方式
这个命令不会因光标位置异常失效，也不依赖当前是否已存在目录——它总是基于当前文档所有 # 至 ###### 标题重新生成。如果你习惯把目录放在文件顶部，建议先把光标移到第一行再执行；如果目录在中间某处，执行后会直接覆盖原位置内容（不是追加）。
常见错误现象：command 'markdown.extension.onXXXKey' not found —— 这不是快捷键没绑好，而是 VS Code 扩展刚加载完、还没完成注册。等状态栏“Activating Extensions”消失后再试，或重启编辑器。
markdown.extension.toc.updateOnSave 开启后，保存即更新，但有前提条件
这个配置项只在目录是用 Create Table of Contents 命令生成的、且未被手动修改结构的前提下生效。一旦你删掉某个列表项、改了链接格式、或混入了非标准 Markdown（比如 HTML 标签），插件就不再识别该区域为“可管理 TOC”，保存时跳过更新。
使用场景：
- 适合长期维护的 API 文档或项目 README，标题增删频繁
- 不适用于临时笔记或含大量自定义锚点的文档
- 中文标题会被转成小写拼音+连字符（如
## 数据预处理→#shu-ju-yu-chu-li），无需额外配置
别依赖 [TOC] 自动替换，它和 Markdown All in One 不兼容
有些用户尝试在文档里手写 [TOC]，指望插件自动替换成目录——这仅在 Markdown Preview Enhanced 插件下有效。Markdown All in One 完全忽略该标记，也不会报错，只是静默跳过。结果就是：你以为开了自动更新，其实每次保存都没反应。
参数差异：
-
Markdown All in One：只响应命令生成的目录块，结构必须是纯列表 + 标准链接 -
Markdown Preview Enhanced：支持[TOC]、[toc]、甚至<!-- toc -->...多种标记语法 - 两者共存时，
[TOC]行会被后者接管，前者完全不干预
中文标题跳转失败？先检查 URL 编码是否被二次处理
VS Code 内置预览和 GitHub 渲染对中文锚点的支持方式不同：前者用 URL 编码（%E6%95%B0%E6%8D%AE），后者用小写拼音（shu-ju）。Markdown All in One 默认按 GitHub 方式生成，所以你在本地预览点击跳转失败，往往是因为用了旧版插件或缓存未刷新。
性能影响很小，但容易被忽略的点：
- 升级插件到 v4.0+（2026 年 6 月后发布）可选开启
markdown.extension.toc.useGitHubStyle - 禁用该选项后，锚点改为 URL 编码，本地预览跳转正常，但 GitHub 上可能失效
- 不要手动改链接 href，插件下次更新会覆盖你的修改
