markdown目录生成失败需先确认插件激活且文件语言模式为markdown；中文标题跳转失效因锚点规则为小写化、去标点、空格转短横线；侧边浮动目录仅markdown preview enhanced支持，需开启预览并手动启用outline。

Markdown目录生成失败？先确认插件是否真正在工作

很多用户以为装了 Markdown All in One 就能自动生成目录，结果敲完 [TOC] 或按快捷键没反应——根本原因是插件没激活或文件没被识别为 Markdown。

检查点如下：

• 确保当前文件后缀是 .md，且右下角状态栏显示 “Markdown” 语言模式（不是 Plain Text）
• Markdown All in One 默认不自动插入 [TOC]，必须手动输入再触发生成：光标放在 [TOC] 行，按 Ctrl+Shift+P → 输入 Create Table of Contents 回车
• 若提示 “command ‘markdown.extension.toc.create’ not found”，说明插件安装后未启用，重启 VSCode 或禁用再启用一次
• 部分项目禁用了扩展（如启用了 "extensions.ignoreRecommendations": true），可在工作区设置里临时关闭

目录链接跳转失效？标题锚点生成规则要记牢

VSCode 自动生成的目录项链接形如 [功能核心价值](#功能核心价值)，但点击后跳不到对应标题，通常不是插件问题，而是 Markdown 标题转锚点的规则被忽略。

关键限制：

• 中文标题会被小写化、去标点、空格转短横线，例如 ## 第一章：VSCode Markdown目录功能概述 → 锚点为 #第一章vscode-markdown目录功能概述
• 含特殊字符（如括号、顿号、引号）的标题会丢失对应部分，### API（v2）更新说明 → 实际锚点是 #apiv2更新说明，不是 #api（v2）更新说明
• 重复标题会导致后出现的锚点加数字后缀，如两个 ## 配置 → 第二个变成 #配置-1，目录里不会体现这个 -1，导致跳转错位
• 避免在标题开头用 emoji 或不可见 Unicode 字符，它们会影响锚点生成，且无法被链接正确解析

想让目录只显示 H2–H4？改配置比删行更可靠

手动删掉目录里不需要的层级既费时又易出错，直接改插件配置一劳永逸。但注意不同插件的配置项名称差异很大。

VSCode

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

下载

以 Markdown All in One 为例，在 settings.json 中添加：

{
  "markdown.extension.toc.levels": "2..4",
  "markdown.extension.toc.unorderedList": false
}

说明：

• "2..4" 表示只提取 ## 到 #### 的标题，H1 和 H5+ 不进目录
• unorderedList 设为 false 会用有序列表（1. 2. 3.）替代默认的无序列表（-），更适合文档编号场景
• Markdown TOC 插件用的是 "markdown-toc.levels"，值格式为 "2-4"，别混用
• 改完保存后，需重新执行 Create Table of Contents 才生效，不会自动刷新旧目录

侧边浮动目录面板怎么开？别被名字误导

很多人搜 “VSCode 侧边目录” 安装一堆插件，结果发现都不是真正意义上的浮动面板——Markdown All in One 和 Markdown TOC 均不支持，只有 Markdown Preview Enhanced 提供该功能，且需额外启用。

操作步骤：

• 安装 Markdown Preview Enhanced（注意不是 Markdown Preview）
• 右键 Markdown 文件 → Markdown Preview Enhanced: Open Preview to the Side
• 预览窗口右上角点击 ⋯ → Toggle Outline，即可呼出可折叠的侧边目录
• 该面板支持滚动跟随高亮，但依赖预览窗口开启；关掉预览，面板就消失，不能像 IDE 那样常驻
• 它不修改源文件，生成的是纯 HTML 渲染结构，所以和 [TOC] 内容可能不一致（比如过滤了某些标题）

真正需要常驻侧边导航的用户，得接受“必须开着预览窗口”这个前提，没有免预览的原生方案。