根本原因是插件未启用自动刷新或配置错误；需确认安装markdown all in one、开启markdown.extension.toc.updateonsave为true、确保唯一[toc]标记，失效时手动执行update table of contents命令。

为什么 Markdown 目录总不自动更新

根本原因不是插件没装，而是默认不监听标题变更。比如你改了 # 新章节，但目录没变，大概率是插件没启用自动刷新，或者你用的是不支持实时更新的老版本插件。

实操建议：

• 确认已安装 Markdown All in One（不是 Markdown TOC，后者不支持保存即刷新）
• 检查设置中是否启用了 markdown.extension.toc.updateOnSave，值必须为 true
• 确保文档里有且仅有一个 [TOC] 标记——多写一个或拼错成 [toc] 都会导致失效
• 如果改完标题后仍不更新，手动按 Ctrl+Shift+P → 输入 Markdown: Update Table of Contents 强制刷新一次，看是否生效

如何让目录只包含 H2 和 H3 级标题

默认生成的目录会把所有 # 到 ###### 都塞进去，实际项目里往往只需要二级和三级结构，比如 API 文档的模块 + 接口列表。

实操建议：

• 在 settings.json 中添加："markdown.extension.toc.levels": "2..3"
• 注意语法：不能写成 "2-3" 或 "2,3"，必须用两个点号 ..
• 如果同时想用有序列表，加一行："markdown.extension.toc.orderedList": true
• 改完保存，再执行一次 Markdown: Create Table of Contents 或重新保存文件

侧边浮动目录面板怎么开

Markdown All in One 本身不提供侧边目录，但配合 Markdown Preview Enhanced 就能实现——而且它支持滚动同步高亮，比静态 TOC 实用得多。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

实操建议：

• 卸载 Markdown All in One 的预览功能（避免冲突）：在设置中关掉 markdown.preview.doubleClickToSwitchEditor
• 安装 Markdown Preview Enhanced，重启 VSCode
• 打开任意 .md 文件，右键 → Markdown Preview Enhanced: Open Preview to the Side
• 预览窗口右上角点击 ⋯ → Toggle Table of Contents，即可固定侧边栏
• 滚动正文时，目录项会自动高亮当前所在章节

目录链接跳转失败常见原因

点击目录里的 [简介](#简介) 却跳不到对应标题，基本不是插件问题，而是标题 ID 生成规则被破坏了。

实操建议：

• 中文标题会被转成小写、去标点、空格变短横线，例如 ## 第一章：快速入门！ → #第一章快速入门，所以链接必须匹配这个 ID
• 避免在标题里用 +、&、® 等特殊字符，它们可能被过滤或编码异常
• 如果标题以数字开头（如 1. 安装步骤），部分渲染器会忽略，建议加个字母前缀：1-安装步骤
• 检查是否启用了 markdown.extension.toc.slugifyMode，推荐设为 github（兼容 GitHub 渲染）

真正卡住人的，往往是标题 ID 和链接之间那层看不见的映射关系——它不报错，只静默失效。调目录时，先看预览里生成的链接 href 是什么，再对比目标标题实际生成的锚点，差一个字符就跳不动。