toc.levels 配置需在用户或工作区 settings.json 中设为字符串如 "1..6" 或 "2..5"，保存后必须完全重启 VSCode 才生效；手动编辑过的 [TOC] 块会被标记为 dirty 而禁用自动更新，应置于文档末尾并确保上方有空行。
Markdown All in One 的 toc.levels 配置怎么写才生效
直接改 markdown.extension.toc.levels 的值不生效，大概率是因为你没重启 VSCode 或没在正确的作用域下设置。这个配置只在用户或工作区设置里生效，且必须是字符串格式，不是数字数组。
- 正确写法是
"1..6"或"1-6"（两者都支持），不能写成[1,2,3,4,5,6]或1..6（没引号） - 如果只想从二级标题开始生成目录，设为
"2..6"；想排除 H6，就用"1..5" - 修改后必须保存 settings.json 并**完全关闭再重开 VSCode**——热重载不触发插件配置重新加载
- 检查是否被更高优先级设置覆盖：打开命令面板
Ctrl+Shift+P→ 输入Preferences: Open Settings (JSON)，确认该配置没出现在多个层级中（比如同时在用户和工作区里，后者会覆盖前者）
为什么手动编辑过的 [TOC] 块不再自动更新
这不是 bug，是插件的保护机制：一旦检测到 [TOC] 区域内存在非自动生成内容（比如手加的注释、链接、空行、缩进），toc.updateOnSave 就会静默退出，避免覆盖人工修改。
- 典型触发场景：
[TOC]后面紧跟着<!-- 自定义说明 -->，或目录项里混入了[手动链接](#xxx) - 临时绕过方法：光标放在 [TOC] 块内，执行
Markdown: Update table of contents - 长期方案：把 [TOC] 块单独放在文档末尾，并确保它上方有**至少一个空行**，插件会将其识别为“隔离区域”，允许自动更新的同时保留结构自由度
- 别依赖“删掉重生成”来修复——只要块内有过手动改动，插件就会打上“dirty”标记，后续 save 都跳过自动刷新
多个 Markdown 目录插件共存时谁起作用
VSCode 不协调插件间的功能冲突，而是按**激活顺序 + 贡献点声明**决定最终行为。装了 Markdown All in One 和 Markdown TOC 同时启用，很可能只有前者响应 Ctrl+K Ctrl+T。
- 查实际生效者：右键编辑器 → “格式化文档” 或 “创建目录”，看弹出菜单里列出的是哪个插件的命令
- 禁用次要插件是最稳妥解法——不是卸载，而是勾选“禁用工作区”或“禁用全局”，避免后台争抢事件监听
- 某些插件（如
Markdown Preview Enhanced）会劫持预览窗口的渲染逻辑，导致Markdown All in One的 TOC 链接在预览里失效；这时要关掉它的markdown-preview-enhanced.enableFrontMatterToc - 插件间无通信协议，不存在“主从协作”——所谓“扩展性”其实是靠你主动裁剪冗余能力换来的
导出 PDF 时目录丢失的真正原因
Markdown All in One 本身不参与导出，它只负责在编辑器里生成 HTML 片段。PDF 导出由 Markdown PDF 或系统打印等外部流程完成，而它们根本看不到插件注入的 DOM 结构。
- 常见假象：目录在预览里正常显示，但导出后只剩文字没链接——因为导出工具只解析原始 Markdown，不执行插件 JS
- 解决路径分两条：要么换支持 TOC 渲染的导出器（如 Typora 导出、Pandoc + custom CSS），要么在导出前用
Markdown: Export to HTML生成含完整 TOC 的 HTML，再转 PDF - 如果坚持用
Markdown PDF，必须开启markdown-pdf.includeDefaultStyles，否则插件生成的 class（如md-toc）会被 CSS 重置抹掉样式 - 注意：GitHub README 页面能正确渲染 TOC，是因为 GitHub 的渲染器原生支持
[TOC]语法；本地导出永远无法 100% 复现，这是架构层面的限制
实际用下来，最难绷的是“自动更新”和“导出一致性”这两块——它们表面是功能开关，背后其实是编辑器扩展模型与导出工具链之间的断层。插件再聪明，也跨不过 VSCode 插件 API 不暴露 DOM 渲染上下文这道坎。
