在之前写的《用 VSCode 打造宇宙最强 Markdown 编辑器》系列几篇博文已经讲解了用 VSCcode + Markdown 插件编写文档的基础技能，对于文章的目录列表 TOC，最初试验时发现 MPE 插件已内置了类似 Markdown TOC 插件的 TOC 生成功能，创建目录列表就是小菜一碟。不过在写了几篇中文贴之后突然发现，Markdown文档的 TOC 对中文字符编码的目录列表的支持问题多多，网上查到的所有方法都存在问题。只好自力更生，整理了一个可以说目前为止最完美的中文目录列表生成方法，和我整理的 TOC 功能汇总资料，一并分享给大家。

VSCode 中用 MPE 编写 Markdown，支持通过 [TOC] 语法将目录插入到文档的任何位置，同时还会在侧边栏显示相同目录，便于预览时选择跳转。需要注意的是：这种方式创建的 TOC 目录只会在预览中显示，或在浏览器或生成 PDF 等文档浏览，不会修改你的 markdown 文件。并且可以点击预览窗口中的侧边栏目录列表图标，打开侧边栏目录。如下图。

需要特别注意:必须是以 MPE 插件的 Markdown 预览功能，而不是打开 VSCode 自有的 Markdown 预览窗口。 VSCode 自有的 Markdown 预览不支持目录列表的显示。

博客园网站编辑界面上，要求 [TOC] 必须独占一行。和 VSCode 的 MPE 插件功能类似，如下图：

CSDN 的博客编辑界面中，录入 [TOC] 时，会将 [TOC] 自动转换成 @[TOC]。另外，可以在 @[TOC] 后面增加目录名称，如：@[TOC](目录名称)，但这个后面增加目录名称的语法扩展在 VSCode 的 MPE 插件不支持。

开源中国 OSChina 网站，在 Markdown 博客撰写界面上没有 [TOC] 自动生成目录功能。

简单的 [TOC] 目录只能自动显示 Markdown 的 1-6 级目录，不能限定从第 2 级或者第 3 级开始，更不能调整目录的格式等，功能有较大限制。在 MPE 插件支持通过文档头部编写 front-matter ，对[TOC]语法所自动展示的目录进行设置，例如，在文件头增加如下这段 front-matter 代码：

在没有定义front-matter时，效果如下：

front-matter 代码对 TOC 目录格式的定义同时影响到文档中的 [TOC] 标识自动生成的目录和预览窗口侧边栏目录的显示效果。定义之后预览结果如下图所示：

对于只用 MPE 插件浏览，或通过 MPE 插件转存 pdf/html/doc 格式等用途，可以考虑使用此扩展功能。如果 Markdown 文档会被用来复制粘贴到博客网站等界面上发表，则要考虑网站本身的兼容性问题。大多数网站并不支持这项功能。

通过 Markdown Preview Enhanced 插件可以实现基于 markdown 文件生成目录列表 ( TOC ) 并插入/更新到 Markdown 文档中，其功能与 Markdown TOC 插件基本类似。这里详细介绍一下其操作方法：

步骤 1: 将光标放在文档中要生成目录并插入的位置；

步骤 2: 按快捷键 ctrl + shift + p ，或 鼠标右键菜单，调出命令面板；

步骤 3: 在命令面板中，搜索并选择：Markdown Preview Enhanced: Create Toc，将会在光标位置插入目录生成代码如下：

步骤 4: 可以手工修改代码中的参数，以实现不同的目录列表效果。自动生成代码中：depthFrom=1 depthTo=6 表示从一级标题到六级标题，命令行中各参数说明：

orderedList 是否使用有序列表

depthFrom [1~6] 开始目录层级

depthTo [1~6] 明细目录层级

ignoreLink 如果设置为 true，那么 TOC 将不会被超链接。

步骤 5: 在确认 MPE 预览窗口打开的状态下，点击保存或按 ctrl + S, MPE 将根据参数设定，自动生成目录并插入到光标所在位置。生成代码如下所示：

步骤 6: 如果文档结构 ( 各级标题 ) 将不再变化，可以手工清除目录生成所需代码 ( 将 Markdown 粘贴到不同网站时，有些网站会错误的显示出这些代码，导致结果不符合我们的预期，因此在最终版删除掉这些源代码是最安全的做法 ) 。结果如下：

生成目录列表的预览结果见下图：

操作过程注意事项：

通过将目录插入 Markdown 文档的方式，在同一个文档中，可以在任意位置创建多个目录列表 TOCs；

在更新 TOC 时需打开 MPE 预览窗口，大概是目录列表生成时，需要分析预览窗口中 1-6 级标题的 HTML 标签；

每次保存时，目录列表 TOC 会更新，以确保与文章结构一致。所以在保存时，你仍然需要保持预览打开；

补充说明-MPE的预览模式： VSCode 本身自带 Markdown 支持，安装 MPE 插件后有两种 MarkDown 预览 ( Preview ) 方式。VScode Preview 是 VScode 默认是支持 Markdown 的，这种是其自带的预览方式，功能支持比较少。MPE Preview 支持的功能比较多。进入 MPE Preview 有如下 3 种方法，如下图：

Markdown 文档编辑窗口右上角，会有两个一样的预览按钮，通常右侧的是 MPE Preview 功能按钮，点击可以进入 MPE Preview 侧边栏预览模式。

安装了 Markdown Preview Enhanced 插件后，在打开的 .md 编辑器窗口中，鼠标右键菜单中，会有一个 「MarkDown Preview ENhanced: Open Preview to the Side」 菜单，选择它后，也会打开 MPE Preview 侧边栏窗口。

用快捷键

如果已经进入了预览窗口，还是傻傻分不清（确实这两种模式有些相像），区分两种预览窗口也很简单，如下图所示：

MPE 插件的 Markdown 预览窗口右上角，增加了 侧边栏目录/刷新页面/回到文档最前面 三个功能按钮，VScode 缺省的预览则没有。

MPE Preview 窗口上，右键鼠标菜单，能看到多种转换输出功能。

安装 Markdown TOC 插件 Markdown TOC 插件参见下图，具体安装方法此处不再赘述。 此插件能够在生成目录列表时，指定 Depth From / Depth To / Ordered List / TOC with Links 等几项配置，这几项功能在 MPE 插件中也可以实现。Markdown TOC 插件有以下 2 个特点：

对目录链接和跳转的功能，增加了锚点 Anchor 的支持，是否生成Anchor, 由扩展配置项：Auto insert anchor for link 来定义。但是，如果标题是中文，其 Archor 的 ID 和 name 的设置仍然是中文。

提供了 github.com 、bitbucket.org、ghost.org 和 gitlab.com 四种 anchor 模式的匹配支持，根据选择不同的网站，按不同的模式生成锚点 Anchor。

用 Markdown TOC 插件生成目录列表 TOC

将光标放在文档中要插入目录列表的位置；

按快捷键 ctrl + shift + p ，或 鼠标右键菜单，调出命令面板；

在命令面板中，搜索并选择：Markdown TOC: Insert/Update ，将会在光标位置插入目录

补充说明： 可以在插件扩展配置中，修改 TOC 参数，以实现不同的目录列表效果

常见问题解决之换行符的正确配置

如果增加目录后没有换行，例如错误的结果如下：

应该是VSCode换行符配置错误导致的，解决方法如下：

以上内容融会贯通的学习完成后，可以轻松生成了带目录列表的 Markdown 文章，就可以很方便的对文档存档和复制到网站上发表了。貌似今天的主题可以写结束语了。。。

等等。。。好像不行阿，文内跳转失灵了。。。

没错，有问题！这样发表后，在很多中文网站，大概是因为链接地址包含有中文或大写英文，加上客户端浏览的编码等问题，会导致文内跳转经常性失效。这怎么办？有没有办法解决这个问题？网上找了半天解决方案，除了手工在标题处建立锚点 Anchor，手工编辑目录列表 TOC，好像也没什么好办法。

Auto Markdown TOC 插件与 Markdown TOC 插件类似，主要区别是其锚点 Anchor 的 ID 对中文的处理，采用了 URL 编码，对后续处理就会比较方便。

安装插件如下图，具体操作步骤不赘述。

对插件做调整，主要修改如下几个配置：

生成目录列表 TOC 方法（与Markdown TOC类似）

将光标放在文档中要插入目录列表的位置；

按快捷键 ctrl + shift + p ，或 鼠标右键菜单，调出命令面板；

在命令面板中，搜索并选择：Markdown TOC: Insert/Update ，将会在光标位置插入目录，并在每个标题下面增加锚点，便于目录链接到每个标题的行内跳转。 但是生成的中文锚点仍然可能无法正常跳转（里面有%和大写英文字母）如下所示：

利用 VSCode 的正则表达式替换功能对锚点ID进行大小写转换。可以通过菜单或按快捷键ctrl+H调出替换操作界面，具体操作方法如下：

选中采用正则表达式

填写查找的正则表达式

填写替换成的字符串的表达式

选择全部替换

整个替换过程需要分如下几个步骤完成

把生成的目录列表中的大写字母替换为小写

查找：

替换为

把标题的锚点ID中的大写字母替换为小写

查找：

替换为

最后，把所有的锚点中文编码中所有的%替换为空

大功告成，最终效果参考我这个文档吧！

虽然整个操作有点儿繁琐，但是确实实现了中文目录列表的完美跳转。

用[TOC]生成目录列表，在各网站中用法有所区别，在网站直接写博客或随笔的时候可以使用；

用 VSCode 写 Markdown 文档，如果只是以 md 文档或转换后进行电子存档，无需复制到网站发表，可以用任何一种方法。

如果希望自己写的这篇 Markdown 文档以后可以复制粘贴到不同的网站中，最好是创建目录列表并插入到 Markdown 文档中，这样可以一次撰写后在任意网站发表，无需担心格式问题。但是如果是中文标题，确实会有些麻烦，不过按我写的这个指引做就可以了。

往期精彩回顾:

原创 Markdown的前世今生 + CSDN的Markdown语法和使用大全

原创 用VSCode打造宇宙最强Markdown编辑器【VSCode篇】

原创 用VSCode打造宇宙最强Markdown编辑器【插件篇】