VSCode配置Markdown目录：一键生成侧边栏与文档索引技巧

VSCode配置Markdown目录：一键生成侧边栏与文档索引技巧

VSCode侧边栏大纲（Outline）能直接显示目录，但默认不启用

很多用户可能没注意到，VSCode其实自带一个轻量级的“大纲”面板，它本质上就是一个侧边目录。不过，这个功能有个小“脾气”：它不会主动跳出来，也不会默认解析所有Markdown文件的标题结构。问题的关键，在于两个容易被忽略的设置项：explorer.experimental.showOutline 和 markdown.preview.toc。

如果你不手动去开启它们，那么侧边栏就永远只会显示“资源管理器”、“搜索”这些常规标签，那个能清晰展示文档结构的标题树，你是看不到的。

• explorer.experimental.showOutline：这个开关直接控制大纲面板是否出现在侧边栏。只有把它设为 true，“OUTLINE”标签才会现身。
• markdown.preview.toc：这个设置决定了在Markdown预览窗口里，是否渲染一个右侧的浮动目录。注意，它和侧边栏的大纲是两回事，但经常被用户混淆。
• 这里有个常见的误区：即使你把 outline.automaticCollapse 设为 false，但如果没打开最基础的 showOutline，大纲面板压根就不会出现。

用 Markdown All in One 插件生成文档内可点击的 TOC 行

侧边栏大纲好用，但它只是个导航工具，内容并不会嵌入到你的文档里。如果你需要一份实实在在的目录，比如要放在.md文件顶部、确保在GitHub上也能正常渲染，或者导出为HTML后依然有效，那就得生成具体的Markdown列表行。

这时候，Markdown All in One插件就成了最稳定的选择。它的优势在于不依赖Pandoc或任何外部服务，命令执行速度快，对中文标题锚点的转换也相当可靠（比如把 ## 中文标题 转换成 [中文标题](#中文标题)）。

• 操作很简单：把光标放在你想插入目录的位置（通常是文件开头），然后按 Ctrl+Shift+P，输入命令 Markdown: Create Table of Contents 即可。
• 生成的链接默认遵循 github-slug 规则：空格变成短横线-，中文会进行URL编码，标点符号则会被剔除。
• 需要注意的是，它不支持自动更新。也就是说，当你修改了文档标题后，旧的目录不会同步变化，你必须手动再运行一次生成命令。
• 当然，也有变通办法：如果你希望每次保存文档时自动重新生成目录，可以在插件的设置里，找到并打开 markdown.extension.toc.autoUpdate 选项。

docsify 侧边栏 TOC 需要独立服务，不是 VSCode 原生能力

不少人在搜索“VSCode Markdown 侧边目录”时，心里想的其实是像Typora那样，左边有一个固定的导航栏，右边是滚动的内容区。很遗憾，这种效果VSCode本身是做不到的——它的预览窗口是一个单页的只读视图，并没有预留左侧菜单区。

想要获得那种沉浸式的阅读体验，你必须启动一个本地的HTTP服务，然后借助像docsify这样的工具来动态渲染文档。这已经不是一个编辑器配置问题，而是架构上的根本差异：VSCode是代码编辑器，而docsify是运行在浏览器端的文档渲染器。

• 使用docsify时，_sidebar.md这个侧边栏文件必须和index.html放在同一级目录下，并且文件名前面的下划线不能少，否则docsify会加载失败，控制台会报404 /_sidebar.md错误。
• 你的文档里至少需要有两个##（二级）或更高级别的标题，因为一级标题#默认是不会被收录到TOC中的。
• 通过命令npx docsify serve .启动服务后，在浏览器访问http://localhost:3000即可。VSCode在这里只负责编辑，文档的刷新由浏览器自动完成。
• 这里有个小坑：不要试图用Live Server这类插件直接打开index.html文件，因为它不会加载_sidebar.md，也不会执行docsify的Ja vaScript初始化逻辑。

中文标题锚点失效？先确认你用的是哪个渲染环境

这是最让人头疼的问题之一：同一个中文标题，在不同的地方生成的锚点链接可能完全不同。VSCode预览、GitHub、docsify、导出的HTML，它们各有各的处理规则。这并非软件缺陷，而是不同平台规范差异导致的。

举个例子，对于标题 ## 数据库连接配置：

• VSCode内置预览：它可能会生成类似 database-connection-configuration 的锚点（拼音转小写加短横线）。
• GitHub：它会使用URL编码后的原始中文，即 %E6%95%B0%E6%8D%AE%E5%BA%93%E8%BF%9E%E6%8E%A5%E9%85%8D%E7%BD%AE。
• docsify：默认采用github-slug模式，行为接近VSCode，但它也支持配置成gitlab或cjk等其他模式。
• 这就导致了一个兼容性问题：如果你手动写了一个链接 [跳转](#数据库连接配置)，它可能只在GitHub上有效；而写成 [跳转](#database-connection-configuration)，才能在VSCode预览和docsify里正常跳转。

所以，如果你的文档需要在多个平台间保持一致的跳转体验，最好不要完全依赖工具自动生成的锚点格式。要么统一使用英文标题，要么在生成目录后，手动检查一下跳转目标是否准确无误。