企业官网建设流程全解析

如何为不同平台生成正确锚点？vim-markdown-toc 详解 GFM/GitLab/Redcarpet/Marked 四种目录风格

【免费下载链接】vim-markdown-tocA vim 7.4+ plugin to generate table of contents for Markdown files.项目地址: https://gitcode.com/gh_mirrors/vi/vim-markdown-toc

vim-markdown-toc 是一款面向 Vim 7.4+ 的Markdown 目录（TOC）自动生成插件：把光标放到想插入目录的位置，输入一条命令，它就能收集标题、按目标平台的锚点规则生成可点击的目录链接，并在保存文件时自动更新——从此告别"目录点不动"的尴尬。

为什么同一份目录换平台就失效？

Markdown 目录的本质是一堆[标题](#锚点)形式的链接，而锚点由谁渲染，就按谁的规则计算。同一个标题在不同平台可能生成完全不同的锚点：

• 在 GitHub 上是#hello-world
• 在 GitLab 上，连续空格会被压缩
• 在 Jekyll（Redcarpet）里，标点符号和 HTML 转义又有另一套逻辑

锚点对不上，点击目录就会原地不动或跳到错误位置。vim-markdown-toc 的核心价值就是：你只需声明目标平台，锚点计算它全部代劳。

四种目录风格怎么选？一张表看懂

💡 将光标放在要插入目录的行，执行对应命令即可。默认只收集光标之后的标题；如需包含光标之前的标题，可设置选项g:vmt_include_headings_before。

GFM 锚点规则：最常见的一套

GFM（GitHub Flavored Markdown）规则是大多数人最需要的：

1. 标题全部转小写
2. 去除特殊符号，但保留中日韩文字、西里尔字母、阿拉伯字母及带重音的拉丁字母
3. 空格替换为-（每个空格一个）
4. 同名标题自动追加-1、-2，模拟 GitHub 的去重行为

用真实用例感受一下（取自 test/GFM.md）：

GitLab 风格：与 GFM 的三个小差别

GitLab 解析器的规则与 GFM 很像，但注意这三点：

• 连续空格压缩为单个-：## Hello Markdown→hello-markdown
• 下划线保留，但首尾的下划线会被去掉：_Hello_World_→hello_world
• 平假名、片假名和谚文不被保留

Redcarpet 风格：Jekyll 用户的专属

Redcarpet 规则先做HTML 实体转义（&、"、'），再把一长串标点统一替换成-，最后压缩多余连字符并去掉首尾连字符：

• ### (Hello()World)→hello-world
• # &你好&世界&→amp-你好-amp-世界-amp

📌 与 GFM 不同，Redcarpet 规则不会给重名标题追加序号，因此 Jekyll 站点中尽量让标题保持唯一。

Marked 风格：最宽容的一条路

Marked 规则最简单粗暴：只把连续空格换成-，其余原样保留（仅整体小写）：

• ## `Hello World`→`hello-world`（反引号都保留）
• ## 你好！→你好！
• 甚至标题里的完整链接语法text也会被原样带进锚点

它专为 markdown-preview.vim 的预览锚点行为设计，其他平台请勿误用。

围栏机制：保存时自动更新目录的秘密

执行:GenTocGFM后，目录会被一对围栏注释包住：

<!-- vim-markdown-toc GFM -->…<!-- vim-markdown-toc -->

围栏里记录了所用风格。之后每次保存，插件自动找到围栏、按原风格重新生成目录，标题怎么改都不会坏。相关技巧：

• :UpdateToc手动刷新；:RemoveToc删除目录；:TocGoto在目录行上直接跳到对应标题
• 围栏里不写风格时，用g:vmt_fence_hidden_markdown_style指定默认值
• 不想要围栏？设置g:vmt_dont_insert_fence = 1（代价是失去保存时自动更新）

常见问题解答

❓中文标题安全吗？安全。GFM 与 GitLab 规则均保留 CJK 字符，## 第三章！会生成#第三章这样的锚点。

❓只想生成纯文字目录、不要链接？设置g:vmt_link = 0，输出只有缩进的标题列表。

❓能控制收录的标题级别吗？能。g:vmt_min_level（默认 1）和g:vmt_max_level（默认 6）可以只收录二到三级标题等区间。

❓命令没反应？运行:set ft确认文件类型是markdown，插件只在这类后缀（.md、.markdown、.mkd等）下工作。

相关文件导航

• 插件全部逻辑（仅一个文件）：ftplugin/markdown.vim
• GFM 锚点全量用例：test/GFM.md
• Marked 锚点全量用例：test/Marked.md
• 四种风格的锚点单元测试：test/test.vim
• 完整文档与安装说明：README.md

🚀小结：先判断文档最终在哪个平台渲染（GitHub / GitLab / Jekyll / 本地预览），再选对应的:GenTocXXX命令，配合围栏自动更新，就能为任何 Markdown 文件生成一份"点击必中"的目录。

【免费下载链接】vim-markdown-tocA vim 7.4+ plugin to generate table of contents for Markdown files.项目地址: https://gitcode.com/gh_mirrors/vi/vim-markdown-toc