MarkdownTOC

Markdown 文档中生成目录 (TOC) 的 Sublime Text 3 插件。

注意：v3.0.0 版本有重大变更。请参阅升级指南以获取更多详细信息。

目录

• 快速开始
• 功能特点
  • 根据 Markdown 文档中的标题插入目录
  • 当 Markdown 文档保存时自动刷新目录
    • 支持的文件扩展名
  • 使用属性自定义生成目录
  • 当标题有锚点时自动锚定
  • 为可点击目录自动添加链接
    • ids 中的小写化
      • 保留大小写
      • 将所有字符小写化
    • 自动链接 ids 的操作
    • URI 编码
    • 兼容 Markdown 预览
    • 链接前缀
  • 控制目录中的列表层级
  • TOC 元素的有序或无序样式
  • 自定义 TOC 列表符号
  • 指定自定义缩进前缀
  • 在标题中保留图片
  • 排除标题
• 用法
• 提示
  • 如何删除 MarkdownTOC 添加的锚点
  • 处理有关 Github Pages 的问题
  • 使用 Markdownlint 与 MarkdownTOC 一起使用
• 限制
  • 列表中的标题不会被包含在自动生成的目录中
• 属性
• 安装
  • 使用包控制
  • 从 Git
  • 从可下载的存档
• 配置
  • Github 配置
  • 配置和协作
• 兼容性
• 贡献
• 许可
• 作者
• 参考
  • Markdown 目录生成器
  • 与 MarkdownTOC 一起使用的推荐插件

快速开始

1. 安装 MarkdownTOC 插件
2. 打开您的 Markdown 文件
3. 将光标放置在您想插入目录的地方
4. 从菜单中选择：工具 > MarkdownTOC > 插入目录
5. 目录将在 Markdown 文档中插入
6. 保存文档，任务完成

现在您可以继续编辑文档，或者您可以自定义目录，请继续阅读。

功能特点

MarkdownTOC 插件功能丰富，易于定制，适用于单个 Markdown 文档或多篇需要 特殊 目录生成的 Markdown 文档。

• 根据 Markdown 文档中的标题插入目录
• 当 Markdown 文档保存时自动刷新目录
• 使用属性自定义生成目录
• 当标题有锚点时自动锚定
• 为可点击目录自动添加链接
  • ids 中的小写化
    • 保留大小写
    • 将所有字符小写化
  • 自动链接 ids 的操作
  • URI 编码
  • 兼容 Markdown 预览
  • 链接前缀
• 控制目录中的列表层级
• TOC 元素的有序或无序样式
• 自定义 TOC 列表符号
• 指定自定义缩进前缀
• 在标题中保留图片
• 排除标题

根据 Markdown 文档中的标题插入目录

完成插件的 安装 后，您可以根据您的 Markdown 标题自动生成目录。查看 快速入门 以开始使用，或查看 使用部分 以了解如何利用自定义和 配置。

以下是一个示例 Markdown 文档

# Heading 0

Headings before MarkdownTOC tags will be ignored.

◀ place the cursor here and generate the TOC

# Heading 1
Lorem ipsum...

## Heading 2
Lorem ipsum...

MarkdownTOC 插件将默认生成

# Heading 0

Headings before MarkdownTOC tags will be ignored.



- Heading 1
  - Heading 2



# Heading 1
Lorem ipsum...

## Heading 2
Lorem ipsum...

如您从上面的示例中看到的

1. 在 MarkdownTOC 标签部分之上的标题被忽略，只有文档的其余部分被认为是 在范围内

当 Markdown 文档保存时自动刷新目录

如果我们继续编辑 Markdown 文档并添加一个额外的标题

## Heading 3

当我们保存文档时，目录会自动更新。

- Heading 1
  - Heading 2
  - Heading 3



# Heading 1
Lorem ipsum...

## Heading 2
Lorem ipsum...

## Heading 3
Lorem ipsum... (the added text)

删除的标题也是如此，它们会被清除。

也可以通过从菜单中选择：工具 > MarkdownTOC > 更新目录来更新目录，而不需要保存文件。

支持的文件扩展名

请确保您的文件扩展名在以下列表中。

.md .markdown .mdown .mdwn .mkdn .mkd .mark

使用属性自定义生成目录

- [Heading 1](#heading-1)
  - [Heading 2](#heading-2)
  - [Heading 3](#heading-3)



# Heading 1
Lorem ipsum...

## Heading 2
Lorem ipsum...

## Heading 3
Lorem ipsum... (the added text)

1. 目录标签可以使用本地设置覆盖默认 属性 并影响目录的渲染。请参阅：配置 了解如何为插件设置您的默认值。
2. 标题可以被自动链接（见：自动链接）
3. 标题可以有自动链接的锚点（见：当标题定义了锚点时自动锚定）

默认行为也可以描述如下

请参阅：Github 配置 了解如何针对 Github 使用配置 MarkdownTOC。

当标题有锚点时自动锚定

您可以在标题前自动添加一个 HTML 锚点（<a name="xxx"></a>）。

# Heading with anchor [with-anchor]

目录生成可以指定遵循此规则，并生成以下格式的目录元素

- [Heading with anchor](#with-anchor)

请注意，默认的属性 autoanchor 的值为 false。您可以自动在标题前添加一个 HTML 锚点（<a name="xxx"></a>）。

- [Changelog](#changelog)
- [Glossary](#glossary)
- [API Specification](#api-specification)



<a name="changelog"></a>
# Changelog
Lorem ipsum...

<a name="glossary"></a>
# Glossary
Lorem ipsum...

<a name="api-specification"></a>
# API Specification
Lorem ipsum...

请注意，autolink 的默认值为 false，由 属性 defaults.autoanchor 定义。另请参阅：如何移除 MarkdownTOC 添加的锚点。

为可点击目录自动添加链接

插件可以被指定来自动链接标题，这样您就得到了一个带有 可点击 �超链接元素的目录。

以下是一个示例文档

# Heading 1
Lorem ipsum...

## Heading 2
Lorem ipsum...

## Heading 3
Lorem ipsum...

将 autolink 设置为 true 将渲染以下内容

- [Heading 1](#heading-1)
  - [Heading 2](#heading-2)
  - [Heading 3](#heading-3)
  - [Heading 4](#heading-4)
- [Heading with anchor](#with-anchor)

自动链接的标记样式可以是以下之一

• round，默认样式，Github 上支持的样式。
• square，与 “Markdown 标准参考链接” 风格。

请注意，autolink 的默认值为 false，由 属性 defaults.autolink 定义。

- MarkdownTOC Plugin for Sublime Text
  - Feature
  - Feature
  - Feature

- [MarkdownTOC Plugin for Sublime Text](#markdowntoc-plugin-for-sublime-text)
  - [Feature](#feature)
  - [Feature](#feature-1)
  - [Feature](#feature-2)

圆括号：遵循GitHub样式。

- [Heading](#heading)

方括号：遵循 “Markdown标准参考样式链接”。

- [Heading][heading]

请注意，方括号的默认值为由属性 defaults.bracket定义的round。

ids 中的小写化

默认情况下，该插件仅将ASCII字母（从a到z）转换为小写，以自动创建链接。

- [ПРИМЕР EXAMPLE][ПРИМЕР-example]



# ПРИМЕР EXAMPLE

这与将lowercase属性设置为only_ascii相同。

- [ПРИМЕР EXAMPLE][ПРИМЕР-example]



# ПРИМЕР EXAMPLE

保留大小写

您可以通过将lowecase属性设置为false来禁用小写能力。

- [One Two Three][One-Two-Three]



# One Two Three

将所有字符小写化

此外，您还可以通过将lowercase属性设置为all（或除false和only_ascii之外的其他任何值）来扩展小写能力。

- [ПРИМЕР EXAMPLE][пример-example]



# ПРИМЕР EXAMPLE

您也可以在键配置中使用defaults.lowercase指定此内容。

自动链接 ids 的操作

您还可以使用键id_replacements在您的配置中操作链接ID。

{
  "id_replacements": [
    {
      "pattern": "\\s+",
      "replacement": "-"
    },
    {
      "pattern": "!|#|$|&|'|\\(|\\)|\\*|\\+|,|/|:|;|=|_|\\?|@|\\[|\\]|`|\"|\\.|<|>|{|}|™|®|©|&lt;|&gt;|&amp;|&apos;|&quot;|&#60;|&#62;|&#38;|&#39;|&#34;",
      "replacement": ""
    }
  ]
}

1. 每个集合允许使用正则表达式
   • 它将被简单地扩展为Python的re.sub(pattern, replacement, id)
2. 替换序列的执行顺序从上到下

示例

# Super Product™

此标题的链接改为以下ID

#super-product

• 空格（' '）替换为短划线（'-
• '™'被替换为无，因为'™'被包含在第二个集合中

URI 编码

默认情况下，非ASCII字符在链接ID中会被URL编码。

- [Ejemplos de español](#ejemplos-de-espa%C3%B1ol)
- [日本語の例](#%E6%97%A5%E6%9C%AC%E8%AA%9E%E3%81%AE%E4%BE%8B)
- [Примеры русского](#%D0%9F%D1%80%D0%B8%D0%BC%D0%B5%D1%80%D1%8B-%D1%80%D1%83%D1%81%D1%81%D0%BA%D0%BE%D0%B3%D0%BE)
- [中国的例子](#%E4%B8%AD%E5%9B%BD%E7%9A%84%E4%BE%8B%E5%AD%90)



# Ejemplos de español
# 日本語の例
# Примеры русского
# 中国的例子

如前所述，您可以通过将uri_encoding属性设置为false来禁用此功能，如下所示：uri_encoding="false"。

- [Ejemplos de español](#ejemplos-de-español)
- [日本語の例](#日本語の例)
- [Примеры русского](#Примеры-русского)
- [中国的例子](#中国的例子)



# Ejemplos de español
# 日本語の例
# Примеры русского
# 中国的例子

兼容 Markdown 预览

如果您想使用MarkdownTOC与Markdown Preview一起使用，您应使用markdown_preview属性。您可以将其设置为markdown或github。

当设置为markdown时，您可以获取MarkdownPreview的markdown解析器渲染的相同链接。

- [Hello 世界 World](#hello-world)
- [ESPAÑA](#espana)
- [ПРИМЕР RUSSIAN](#russian)



# Hello 世界 World
# ESPAÑA
# ПРИМЕР RUSSIAN

当设置为github时，您可以获取MarkdownPreview的github解析器渲染的相同链接。

- [Hello 世界 World](#hello-%25E4%25B8%2596%25E7%2595%258C-world)
- [ESPAÑA](#espa%25C3%25B1a)
- [ПРИМЕР RUSSIAN](#%25D0%25BF%25D1%2580%25D0%25B8%25D0%25BC%25D0%25B5%25D1%2580-russian)



# Hello 世界 World
# ESPAÑA
# ПРИМЕР RUSSIAN

目前不支持其他解析器。

如果您想禁用此功能，请将其设置为false。

链接前缀

您还可以设置链接的前缀。

- [My Heading](#user-content-my-heading)



# My Heading

您可以使用键defaults.link_prefix在您的配置中操作此内容。

控制目录中的列表层级

# Heading 1
Lorem ipsum...

## Heading 2
Lorem ipsum...

### Heading 3
Lorem ipsum...

#### Heading 4
Lorem ipsum...

使用默认级别

- Heading 1
  - Heading 2
    - Heading 3
      - Heading 4

设置级别为1,2

- Heading 1
  - Heading 2

请注意，属性的默认级别为"1,2,3,4,5,6"，这意味着将包含所有标题大小。

您还可以在键defaults.levels中使用配置指定此内容。

根据Markdown规范，标题的最大大小为6。

TOC 元素的有序或无序样式

插件支持两种TOC元素列出样式

• 无序列表
• 有序列表

具有以下内容的Markdown文档

# Heading 1
Lorem ipsum...

## Heading 2
Lorem ipsum...

### Heading 3
Lorem ipsum...

### Heading 4
Lorem ipsum...

## Heading 5
Lorem ipsum...

# Heading 6
Lorem ipsum...

将使用样式unordered

- Heading 1
  - Heading 2
    - Heading 3
    - Heading 4
  - Heading 5
- Heading 6

以及样式ordered

1. Heading 1
  1. Heading 2
    1. Heading 3
    1. Heading 4
  1. Heading 5
1. Heading 6

请注意，属性的默认值为：unordered。

您可以在配置中通过键defaults.style设置默认样式。

自定义 TOC 列表符号

您可以为每个级别定义用于TOC的列表项。第一个项目是第一级别，第二个是第二级别，依此类推，直到目前为止列表的最后一个项目，然后重新从开始。

- foo
  + bar
    * baz
      - foo
        + bar
          * baz

您可以通过键defaults.bullets在您的配置中设置默认列表项。

上述示例也可以描述为

{
  "defaults": {
    "bullets": ["-","+","*"]
  }
}

您还可以在属性中设置它。在这种情况下，值的类型是 “逗号分隔的字符串”。

指定自定义缩进前缀

缩进前缀是用于缩进 TOC 元素的字符串的指定。

一个丑陋但具有说明性的例子可能是使用一个 表情符号。

- [Heading 1](#heading-1)
:point_right: - [Heading 2](#heading-2)
:point_right: :point_right: - [Heading 3](#heading-3)
:point_right: :point_right: - [Heading 4](#heading-4)
:point_right: - [Heading 5](#heading-5)
- [Heading 6](#heading-6)

请注意，属性的默认值是：'\t'。

您可以通过配置中的键defaults.indent来设置您的默认缩进。

在标题中保留图片

如果您想保留标题中的图片，请将remove_image设置为false。

- ![check](check.png) Everything is OK



# ![check](check.png) Everything is OK

请注意，属性的默认值是：false。

- Everything is OK



# ![check](check.png) Everything is OK

您可以通过配置中的键defaults.remove_image来更改您的默认设置。

排除标题

您可以通过在标题行上方添加特殊注释来从 TOC 中排除某些标题，如下所示。

## This heading will be excluded

用法

1. 打开您的 Markdown 文件
2. 将光标移至您想插入 TOC 的位置
3. 从菜单中选择：工具 > MarkdownTOC > 插入目录
4. TOC 已插入文档
5. 使用属性或配置评估您的 TOC 并进行定制
6. 更新内容并保存…
7. TOC 已更新

如果您想要在每次保存时更新，请不要删除注释标签。

提示

如何删除 MarkdownTOC 添加的锚点

如果您想要再次删除 TOC，您无需遍历您的整个 Markdown 并手动删除所有标签 - 只需遵循这个简单的指南（另请参阅：当标题已定义锚时自动锚定）。

1. 打开您的 Markdown 文件
2. 将属性autoanchor设置为false，这将清除所有锚点

请参阅下面的动画演示更改

3. 现在从开头到结尾删除 TOC 部分，并且 **MarkdownTOC** 集成就会消失

...

参考：Github 问题 #76

处理有关 Github Pages 的问题

如果您正在使用 Github Pages，您可能会发现某些主题无法正确渲染标题。

这可以通过将autoanchor设置为false简单地解决

Jekyll完成时，您的标题应能正确渲染。

参考：Github 问题 #81

使用 Markdownlint 与 MarkdownTOC 一起使用

如果您正在使用 Markdownlint（Node 实现），它将默认报告几个违规。

您可以使用以下基本配置来解决这些问题

{
    "html": false,
    "blanks-around-headings": false,
    "ul-indent": {
        "indent": 4
    }
}

• 将html设置为false，因为 MarkdownTOC 依赖于 HTML 标签来协助 Markdown
• blanks-around-headings应设置为false，因为锚点位于 TOC 中列出的标题附近
• ul-indent应将它的参数indent设置为4，以符合 MarkdownTOC 默认使用的 4，而 Markdownlint 的默认值为 2

如果您已将 MarkdownTOC 配置为不同，您可以根据需要进行调整。

请注意，这个提示基于 Node 实现，可在 GitHub 上找到，它使用基于特定项目的 .markdownlint.json 配置。

限制

MarkdownTOC确实有一些局限性。

有关兼容性的更多信息，请参阅专门部分。

列表中的标题不会被包含在自动生成的目录中

在Markdown 列表中，Markdown 标题的示例，不包括在自动生成的目录中

- # this is a heading

属性

以下属性可用于控制 TOC 的生成。

您可以通过包首选项定义自己的默认值，这是Sublime Text允许用户自定义包设置的方式。有关MarkdownTOC的更多详细信息，请参阅配置部分。

安装

使用包控制

1. 运行“Package Control：安装包”命令，找到并安装MarkdownTOC插件。
2. 重启Sublime Text

包控制

从 Git

git clone [email protected]:naokazuterada/MarkdownTOC.git ~/Library/Application\ Support/Sublime\ Text\ 3/Packages/MarkdownTOC

从可下载的存档

1. 下载zip文件并将其解压。
2. 打开Sublime Text Packages/目录（选择菜单：Sublime Text > 首选项 > 浏览包）。
3. 将MarkdownTOC/目录移动到Packages/目录。

配置

您可以通过使用属性来自定义单个Markdown文档中的TOC，但如果您想在不同Markdown文档中使用相同的TOC配置，您可以配置自己的默认值。

选择：Sublime Text > 首选项 > 包设置 > MarkdownTOC > 设置 - 用户

或者您可以通过手动创建文件来创建文件~/Library/Application Support/Sublime Text 3/Packages/User/MarkdownTOC.sublime-settings

示例：MarkdownTOC.sublime-settings

{
  "defaults": {
    "autolink": true,
    "bracket": "square",
    "levels": "1,2",
    "indent": "    ",
    "remove_image": false,
    "bullets": "*",
    "style": "ordered"
  },
  "id_replacements": [
    {
      "pattern": "\\s+",
      "replacement": "-"
    },
    {
      "pattern": "&lt;|&gt;|&amp;|&apos;|&quot;|&#60;|&#62;|&#38;|&#39;|&#34;|!|#|$|&|'|\\(|\\)|\\*|\\+|,|/|:|;|=|_|\\?|@|\\[|\\]|`|\"|\\.|<|>|{|}|™|®|©",
      "replacement": ""
    }
  ]
}

请参考属性部分的概述，以及自定义TOC生成的部分。

配置优先顺序如下：

1. MarkdownTOC开始标签中指定的属性（参见：使用属性自定义TOC生成）
2. MarkdownTOC设置 - 用户（本部分）
3. MarkdownTOC设置 - 默认（参见：属性）

关于属性属性的特定行为概述，请参阅以下列表。

• defaults.autolink，（参见：可点击TOC的自动链接）
• defaults.autoanchor，（参见：标题有锚点定义时的自动锚定）
• defaults.bracket，（参见：可点击TOC的自动链接）
• defaults.indent，（参见：指定自定义缩进前缀）
• defaults.link_prefix，（参见：链接前缀）
• defaults.levels，（参见：控制TOC中列出的级别）
• defaults.bullets，（参见：自定义TOC中的列表符号）
• defaults.lowercase，（参见：在ID中的小写）
• defaults.remove_image，（参见：保留标题中的图片）
• defaults.style，（参见：TOC元素的有序或无序样式）
• defaults.uri_encoding，（参见：URI编码）
• defaults.markdown_preview，（参见：与Markdown预览兼容）
• id_replacements，（参见：自动链接ID的操控）

Github 配置

以下是一个主要用于 GitHub 的 Markdown 设置配置示例

{
  "defaults": {
    "autolink": true,
    "bracket": "round",
    "lowercase": "only_ascii"
  }
}

配置和协作

请注意，如果您与其他哈哈哈和 MarkdownTOC 用户合作，您可能会简单地因为配置不同而进行来回更改。

如果情况如此，并且您无法就配置达成一致，则请选择使用文档中指定的属性指定的配置。

文件中配置设置的属性配置示例

兼容性

这绝对不是一份详尽的列表，欢迎您提供更多信息和建议。以下是列出的 Markdown 渲染平台和工具，其中已经说明与 MarkdownTOC 插件的兼容性和不兼容性。

贡献

非常欢迎您的贡献，请参阅贡献指南 https://github.com/naokazuterada/MarkdownTOC/blob/master/.github/CONTRIBUTING.md

许可

• MarkdownTOC 采用 MIT 许可证

作者

• Naokazu Terada

参考

• Daring Fireballs Markdown 语法规范
• Sublime Text
• Sublime Text: 包管理器
• 表情符号快捷表
• GitHub 风格 Markdown
• Markdown 预览

Markdown 目录生成器

以下是一份其他 Markdown 目录生成器的列表，仅供参考可能还会在 MarkdownTOC Sublime Text 插件不适合的任务场景中使用。请注意，这份列表绝不是权威的或详尽的，而且不提供推荐，因为我们只能推广 MarkdownTOC 对 Markdown 目录生成器的工具箱所做的贡献。

• doctoc Node (npm) 实现带 CLI 接口
• markdown-toclify Python 实现带 CLI 接口

与 MarkdownTOC 一起使用的推荐插件

• Markdown Numbered Headers Sublime Text 3 插件，自动插入/更新/删除标题数字