VSCode中Markdown文件无大纲，需先确认语言模式为Markdown、标题语法规范（#开头无空格）、文件在工作区内且编码为UTF-8；Outline仅解析ATX标题，跳过frontmatter和代码块内内容。
VSCode 里 Markdown 文件没大纲？先确认是否启用了内置预览支持
VSCode 自 1.80 起已将 markdown.preview.enabled 设为默认开启，但如果你的侧边栏没出现大纲（Outline）视图，大概率是当前文件没被识别为 Markdown —— 检查右下角状态栏语言模式是否显示 Markdown。如果不是，点击它，手动选择 Markdown；否则 Ctrl+Shift+P（macOS 为 Cmd+Shift+P）输入 Change Language Mode 再选。
注意：只有以 .md 或 .markdown 结尾的文件，且内容符合基本标题语法（# H1、## H2 等），才会触发大纲解析。空文件、纯文本无标题、或混用缩进式标题（如 Chapter 1\n========）不会出现在 Outline 中。
Outline 面板不显示标题？检查标题层级和格式是否合法
VSCode 的大纲基于 VS Code 自带的 vscode.markdown-language-features 扩展解析，只识别 ATX 标题（即 # 开头），不支持 Setext 式（=== / --- 下划线标题）。以下情况会导致标题“消失”：
-
# 标题前有空格或制表符 → 不解析（必须顶格或仅含 1 个 tab 缩进） -
## 标题行尾有多余空格 → 大纲中可能显示为空项或跳过 - 使用中文全角符号如
＃（U+FF03）代替#→ 完全不识别 - 标题内含未转义的 HTML 标签如
# <span>标题</span>→ 解析中断，后续标题可能错位
验证方式：打开命令面板，运行 Developer: Toggle Developer Tools，在 Console 中输入 vscode.workspace.textDocuments.find(d => d.fileName.endsWith('.md'))?.languageId，确认返回 'markdown'；再看 Outline 面板是否响应光标定位到标题行时的高亮联动。
想生成可点击的 TOC（目录）？别依赖 Outline，用插件或脚本生成静态内容
VSCode 的 Outline 是导航视图，不是插入到文档里的目录。要生成实际写入文件的 TOC（例如 GitHub 渲染后可见），需额外处理：
- 推荐插件：
Markdown All in One（作者 yzane），安装后按Ctrl+Shift+P运行Markdown All in One: Create Table of Contents，会自动提取当前文档所有#–#####标题并生成带锚点链接的列表 - 注意配置：
markdown.extension.toc.levels控制生成几级标题（默认是 2–6），markdown.extension.toc.slugifyMode影响锚点生成逻辑（如是否小写、去标点） - 若用
docsify或VuePress构建站点，应禁用插件自动生成，改用其内置 TOC 组件，避免重复或冲突 - 手动插入 TOC 后，插件默认不会自动更新——需再次触发命令，或启用
markdown.extension.toc.autoUpdate（但频繁修改标题时可能误删手动加的内容）
大纲乱序、跳级或缺失？优先排查 frontmatter 和代码块干扰
VSCode 的 Markdown 解析器会跳过 YAML frontmatter 区域（---\nkey: value\n---）和代码块（
...）内的内容，但若格式不规范，会影响整篇解析：
- frontmatter 缺少闭合
---→ 后续所有标题被当成 frontmatter 内容，不出现在大纲 - 代码块用错了标记，比如写成
~~~或漏掉语言标识 → 解析器可能提前结束代码块，导致后续标题被吞 - 标题写在引用块里：
> ## 这不是标题→ 不会被识别（引用块内不解析标题） - 使用了非标准扩展语法，如 Obsidian 的
%%collapse或 Typora 的数学块包裹 → 可能破坏 AST 结构，大纲失效
最稳的排查法：新建空白 .md 文件，只写几行标准标题，确认 Outline 正常；再逐段复制原文，观察 Outline 何时中断——通常就能定位到问题段落。
大纲功能本身轻量，但对格式敏感。与其反复调试，不如养成写完标题立刻检查右下角语言模式 + 侧边 Outline 是否同步更新的习惯。一旦发现异常，先看是不是 frontmatter 或代码块“没关好门”。
