目录点不动是因为VSCode原生预览不支持自定义锚点跳转，必须依赖Markdown All in One插件生成的[文本](#anchor)链接；侧边Outline仅显示结构但不可点击，文档内TOC才是可编辑、可提交、支持跳转的真实Markdown块。
为什么 Markdown 目录点不动？检查锚点生成规则
VSCode 原生预览不支持点击跳转到自定义锚点，必须依赖插件生成的 [text](#anchor) 链接才能生效。常见现象是目录项显示正常但点击无反应——本质是没插入可解析的 TOC 块，只是靠大纲视图“看得到”，不是“点得动”。
- 确认已安装
Markdown All in One（非仅Markdown Preview Enhanced），后者默认不生成文档内嵌 TOC - 手动插入的目录块必须以
## 目录或类似二级标题开头，且下方为标准列表格式，例如：- [简介](#简介) - 标题中含中文、空格、标点时，VSCode 会自动转义为 URL-safe 锚点（如
## 环境准备→#环境准备），但## API 接口设计（v2）会被转成#api-接口设计v2，括号和空格全被替换，别按原样手写链接
如何让目录随标题实时更新？别只靠保存
启用自动刷新需两步：插件配置 + 手动触发一次生成。很多人装完插件就以为“自动更新”开箱即用，结果改完标题发现目录没变——因为默认是关闭的。
- 在 VSCode 设置中搜索
markdown.extension.toc.autoUpdate，勾选启用（该配置属于Markdown All in One） - 首次使用必须先执行一次
Markdown: Create Table of Contents命令（Ctrl + Shift + P输入），否则插件不会监听该文件 - 更新后若仍不同步，检查文件是否被排除在工作区外（如出现在
files.exclude列表里），或标题行前有不可见字符（比如全角空格）导致解析失败
侧边大纲（Outline）和文档内 TOC 有什么区别？
两者来源不同、用途不同，混用容易误判效果。侧边 Outline 是语言服务器实时提取符号生成的导航树，而文档内 TOC 是插件根据标题文本生成的可编辑 Markdown 块。
-
Outline面板（Ctrl + Shift + O）无需插件，所有 Markdown 文件都自带，但它不生成链接，也不写入文件，纯属只读视图 - 文档内 TOC 是真实 Markdown 内容，会提交进 Git，影响协作；它支持手动删减条目（比如隐藏某级标题）、加注释、甚至混排其他内容
- 若想让侧边 Outline 显示更准，确保标题语法规范：
#后必须跟一个空格，且不能换行写标题（如#标题不被识别）
多级标题嵌套失效？检查跳级和空行问题
插件解析标题层级时严格依赖 Markdown 语法连续性。跳级（如 ## 后直接写 ####）或标题前后夹杂空行，会导致部分层级被忽略，目录缩进错乱甚至丢失子项。
- 目录最多支持六级（
#至######），但建议控制在四级以内，否则预览渲染易拥挤，且部分导出工具（如 PDF）会截断深层嵌套 - 避免
### 三级和## 二级交错出现，插件按顺序解析，遇到更低层级会视为新分支而非子项 - 标题行前后不要留空行（尤其上方），否则某些版本的
Markdown All in One会漏掉该标题；若必须分段，用
实际用多了就会发现，最难调的不是怎么生成目录，而是怎么让别人打开你的 .md 文件时，目录依然能点、能跳、不丢级——这取决于你写标题时有没有多看一眼空格和层级，而不是等出问题再翻插件文档。
