Markdown 的文章目录在 Vim 里的终极解决方案

如果你使用 Vim 编辑 Markdown ，而且也为如何生成和更新文章目录（ Table of Contents ）而烦恼，那么如下的内容将带你脱离刀耕火种手写 Toc 的体验，回归使用 Markdown 是为了专注于内容的初心。

一言不合先上图：

没错下面就要给你们安利图中演示的这款 Vim 插件了。

插件功能

1. 为 Markdown 文件生成文章目录（ Table of Contents ）。

   目前支持的 Markdown 解析引擎：

   • GFM （ GitHub Flavored Markdown ）
   • Redcarpet

2. 更新已经存在的文章目录。

3. 保存文件时自动更新文章目录。

下载地址

既然它如此的好，那么，哪里可以下载得到呢？

GitHub ：https://github.com/mzlogin/vim-markdown-toc

安装方法

推荐使用 Vundle 来管理 Vim 插件，这样你就可以简单三步完成安装了：

1. 在你的 vimrc 文件里添加如下内容：

   Plugin 'mzlogin/vim-markdown-toc'
   

2. :so $MYVIMRC

3. :PluginInstall

So easy ！当然如果是使用 vim-plug 来管理插件的话跟这步骤一样一样的。

使用方法

生成文章目录

将光标移动到你想放置文章目录的地方，然后运行如下两个命令之一就行：

1. :GenTocGFM

   生成 GFM 链接风格的文章目录。

   适用于 GitHub 仓库里的 Markdown 文件，比如 README.md ，还有用于生成 GitBook 电子书的 Markdown 文件。

2. :GenTocRedcarpet

   生成 Redcarpet 链接风格的文章目录。

   适用于使用 Redcarpet 作为 Markdown 解析引擎的 Jekyll 程序或其它地方。

更新已有目录

使用 :UpdateToc 命令就好了。

其实按默认的配置，保存文件的时候如果发现之前已经使用插件生成过文章目录，就会自动更新，什么都不用做。只有在关闭了自动更新的情况下，才需要使用命令来更新。

配置选项

推荐的用法是就按默认配置，效果杠杠的。但我知道 Vimer 都是不折腾会死星人，一切可控才舒心。

1. g:vmt_auto_update_on_save

   默认值： 1

   用于控制保存文件时是否自动更新已有文章目录。

   如果你确确实实想关闭如此方便好用改变人生的功能，那么在 vimrc 文件里加入如下内容：

   let g:vmt_auto_update_on_save = 0
   

2. g:vmt_dont_insert_fence

   默认值： 0

   用于控制是否插入文章目录前后标志行。

   用插件生成文章目录的时候会在前后插入 <!-- vim-markdown-toc --> 这样的行，这是为了实现保存时自动更新文章目录功能而加入的，使用的是 HTML 的注释语法，在生成的页面里不会看到它们。当然如果你真的不想在源码里看到它们，也是可以让插件生成目录时不插入的，损失就是将无法实现保存文件时的文章目录自动更新这种精华功能，可要想好了。

   关闭方法，在 vimrc 文件里加入如下内容：

   let g:vmt_dont_insert_fence = 1
   

在线案例

看看这个文章目录近百行， GitHub 上 Star 过千的文档项目：

• awesome-adb

对没错它的目录就是用 vim-markdown-toc 维护的，近百行的文件目录如果手动维护准确性和便捷性都无法保证，会痛苦到怀疑人生的。

我使用的与 Markdown 相关的插件

• vim-markdown-toc

  解决文章目录的问题。

• vim-table-mode

  解决表格的排版问题。

• vim-kramdown-tab

  解决 GitHub Pages 的列表缩进问题。

最后附上我的完整 Vim 配置：https://github.com/mzlogin/config-files

好了安利结束，希望这个出自我手，我眼中的终极解决方案能改变你的生活，帮你节省一些宝贵的时间。