mdformat-toc

Mdformat插件，用于生成目录

目录 由mdformat-toc生成

• 描述
• 安装
• 用法
  • 配置
    • 最小和最大标题级别
    • 禁用锚点生成
    • 更改slug函数

描述

Mdformat-toc是一个mdformat插件，它为mdformat添加了自动生成目录（ToC）的功能。ToC将在Markdown文件中用户指定的位置生成。

Mdformat-toc默认为ToC中列出的每个标题创建一个HTML锚点。因此，ToC链接应与任何表现良好的Markdown渲染器兼容（包括GitLab的渲染器）。

可以禁用HTML锚点的生成，在这种情况下，用户应配置一个与所使用的Markdown渲染器兼容的slug函数（目前支持GitHub和GitLab的slug函数）。

安装

pip install mdformat-toc

用法

将以下行添加到您的Markdown文件中。ToC将在该行指示的位置生成。

<!-- mdformat-toc start -->

添加指示行后，只需运行

mdformat <filename>

mdformat将生成ToC。

配置

可以添加参数到指示行以更改ToC的生成方式。具有默认选项的指示行看起来如下：

<!-- mdformat-toc start --slug=github --maxlevel=6 --minlevel=1 -->

在文档中放置多于一条指示线目前不支持。

最小和最大标题级别

用户可以配置要包含在目录表（ToC）中的标题级别范围（以及要“锚定”）。例如，以下配置将仅在目录表中列出第2、3和4级标题

<!-- mdformat-toc start --minlevel=2 --maxlevel=4 -->

禁用锚点生成

默认情况下，将为每个标题附加HTML锚点。例如，以下标题

# Some title

可能格式化为

# Some title<a name="some-title"></a>

这确保了目录表链接不依赖于Markdown渲染器来创建HTML锚点，并使链接具有通用兼容性。

目录表链接默认与GitHub的Markdown渲染器生成的锚点兼容。如果您的Markdown仅在GitHub上托管，您可以禁用mdformat-toc的HTML锚点生成

<!-- mdformat-toc start --no-anchors -->

更改slug函数

Mdformat-toc默认使用GitHub的slug函数。

如果您的Markdown不在GitHub上托管，您可能希望使用GitLab的slug函数

<!-- mdformat-toc start --slug=gitlab --no-anchors -->

注意：与GitLab不同，GitHub要求使用其自己的slug函数才能使目录表链接按预期工作。创建HTML锚点和使用非GitHub的slug函数不是GitHub兼容的，因为GitHub的Markdown渲染器会修改mdformat-toc创建的HTML锚点。默认配置（GitHub slug函数和锚点生成）是唯一与GitHub和GitLab兼容的配置。