vscode outline 面板仅提供只读导航，不生成实际目录；插入可提交、github 可渲染的 toc 必须用插件（如 markdown all in one），且需手动更新，导出 html 时需设置 offline: true 才能保留侧边目录。

VSCode 本身不往 Markdown 文件里插目录，Outline 面板只是侧边导航视图；真要插入可点击、能提交到 Git、GitHub 上也能渲染的 TOC，必须用插件生成静态内容。

为什么 Outline 面板里有标题，但文档里没目录？

Outline 是 VSCode 内置的实时解析视图，只读取 # 开头的 ATX 标题（不支持 === 或 --- 这类 Setext 标题），且完全不写入文件。它不生成任何 Markdown 文本，也不处理 frontmatter 或代码块里的伪标题。所以你看到 Outline 里有层级，不代表文档里已有目录——那是纯 UI 层的导航，不是内容。

• # 标题 前有空格或 tab 缩进超过 1 个 → Outline 可能跳过，更不会进 TOC
• 用了全角 ＃（U+FF03）代替 ASCII # → 完全不识别
• 标题含未转义 HTML，如 # <div>说明</div> → 解析中断，后续标题错位

用 Markdown All in One 插入可提交的 TOC

这是目前最稳定、中文兼容性最好的方案。安装后无需额外配置，默认就能处理中文标题和常见符号。

Markdown Converter 1.0.0

使用 markitdown 将文档和文件转换为 Markdown。适用于转换 PDF、Word (.docx)、PowerPoint (.pptx)、Excel (.xlsx, .xls)、HTML、CSV、JSON、XML 等格式。

下载

• 确保文件后缀是 .md 或 .markdown，且右下角状态栏语言模式为 Markdown
• 光标放在想插入目录的位置（通常在文件开头或 ## 目录 下一行）
• 按 Ctrl+Shift+P（macOS 为 Cmd+Shift+P），输入 Create Table of Contents 并执行
• 生成的链接形如 - [简介](#简介)，锚点自动 URL 编码，GitHub 渲染正常

注意：markdown.extension.toc.levels 控制包含几级标题（默认 2-6），若只要 ## 和 ###，可设为 "2-3"。

导出 HTML 时侧边目录消失？关键在 offline: true

如果你用 Markdown Preview Enhanced 导出 HTML 后发现左侧 TOC 不见了，不是插件坏了，而是资源没打包进去。

• 必须在文档顶部加 frontmatter，且严格顶格、无空行：

  ---<br>html:<br>  toc: true<br>  html_config:<br>    offline: true<br>---

• offline: true 是核心——它把所有 JS/CSS/图标全内联进 HTML，不再依赖网络或本地路径
• 漏掉这行，导出的 HTML 会尝试加载外部脚本，而这些脚本在离线打开时 404，侧边栏直接空白

真正容易被忽略的是：TOC 插入后不会自动更新。结构改了就得删掉旧 TOC，再手动跑一次 Create Table of Contents。没有“监听保存自动刷新”这种事——它生成的是静态文本，不是活的组件。