create table of contents命令不生效，需确认文件为.md且状态栏显示“markdown”、插件已启用并重启vscode、删除冲突的旧版toc.levels配置；update toc仅刷新现有[toc]块，create则在光标处新建目录。
Markdown All in One 是目前最稳定、开箱即用的目录生成方案，其他插件要么功能重叠，要么更新滞后，容易在 VSCode 1.90+ 版本中失灵。
为什么 Create Table of Contents 命令不生效？
常见现象是按下 Ctrl+Shift+P 输入后无响应，或执行后光标处没插入任何内容。
- 确认当前文件后缀是
.md，且未被识别为纯文本（右下角状态栏应显示 “Markdown”） - 检查是否在编辑器内点击了非 Markdown 文件（如
README无后缀，或.txt），VSCode 不会激活该命令 -
settings.json中若设置了"markdown.extension.toc.levels": "2..6"这类旧版配置，会与插件冲突，直接删掉 - 插件启用但未重启编辑器：安装后必须完全关闭 VSCode（包括后台进程），再重新打开
Update TOC 和 Create Table of Contents 的区别在哪？
前者只刷新已有 [TOC] 区域，后者从头生成新目录——但二者依赖同一套标题解析逻辑，行为差异仅在于“是否查找现有标记”。
- 如果你在文档里手动写了
[TOC]或<!-- TOC -->...，运行Update TOC会定位并替换它；Create Table of Contents则无视这些标记，直接在光标位置插入 - 插件默认不监听保存自动更新，想实现“改标题就更新目录”，需手动加配置：
"markdown.extension.toc.autoUpdate": true - 注意：自动更新只作用于当前打开的文件，不会批量扫整个工作区
生成的链接在 GitHub 上点不开？
这是 ID 生成规则不一致导致的，VSCode 默认用 URL 编码方式处理中文标题，而 GitHub 使用更简化的 slug 规则（比如把空格和冒号全转成短横线，忽略括号）。
- 避免在标题中使用
：、（）、【】等符号，优先用英文标点或纯文字 - 中文标题尽量不用长句，例如
## 数据同步失败时的重试机制设计→ 拆成## 重试机制+ 正文说明 - 如果必须保留特殊字符，可手动在链接后加锚点修正，比如
[数据同步失败](#数据同步失败)改为[数据同步失败](#数据同步失败时的重试机制设计)，但这样失去自动生成意义
真正难搞的不是生成目录，而是让不同环境（VSCode 预览、GitHub 页面、导出 HTML）对同一标题生成一致的锚点 ID。这点没有银弹，只能靠标题命名克制 + 少量手动微调。
