在Markdown中显示目录,就是提取文章中所有标题(h1~h6)按层级形成导航树,以方便我们快捷的导航到指定的章节。

手动生成目录

生成章节目录,我们只需要使用链接语法,将标题集中组合在一个列表中即可。以下是一个简单的Markdown示例,展示了如何手动生成目录:

# Markdown目录示例

## 目录
- [引言](#引言)
- [第一部分](#第一部分) 
    - [1.1节](#11节)
    - [1.2节](#12节) 
- [第二部分](#第二部分)

## 引言
 
这里是引言部分的内容。
 
## 第一部分

### 1.1节
这里是第一部分,第一节的内容。
 
### 1.2节
这里是第一部分,第二节的内容。
 
## 第二部分
这里是第二部分的内容。

效果:
Markdown目录示例.jpg

可以看到,目录树已经生成,点击目录就会跳转到具体的内容区域。

自动生成目录

但通过上边的方式生成目录,我们很容易发现问题所在,目录少的时候没问题,当目录多的时候就有些繁琐了,我们需要整理维护所有的章节组成这颗导航树。

再比如我们要调整目录的位置,我们就需要动两个地方,一个是内容区域,一个是目录区域。

因此生成目录我们一般会借助一些工具,比如使用特定的Markdown处理器、第三方工具或插件来自动生成目录。

[TOC]语法生成

大多数Markdown处理器都支持通过特定语法自动生成目录。这个特定语法就是[TOC],在大多数Markdown处理器中,输入[TOC]就可以自动生成文档的目录。

# Markdown目录示例

## 目录
[TOC]

## 引言
 
这里是引言部分的内容。
 
## 第一部分

### 1.1节
这里是第一部分,第一节的内容。
 
### 1.2节
这里是第一部分,第二节的内容。
 
## 第二部分
这里是第二部分的内容。

请注意,不是所有的Markdown处理器都支持自动生成目录,因此需要具体查看Markdown处理器的文档以了解它们是否支持这个功能。

npm语法生成

doctoc

全局安装doctoc:

npm install -g doctoc

创建文件demo.md:

# Markdown目录示例

## 目录
<!-- START doctoc -->
<!-- END doctoc -->

## 引言
 
这里是引言部分的内容。
 
## 第一部分

### 1.1节
这里是第一部分,第一节的内容。
 
### 1.2节
这里是第一部分,第二节的内容。
 
## 第二部分
这里是第二部分的内容。

注意上边目录章节中的书写方式:

<!-- START doctoc -->
<!-- END doctoc -->

doctoc 工具会将目录插入到文件中包含<!--- START doctoc --><!--- END doctoc -->标记之间的位置。我们可以将这些标记插入到Markdown文件中,然后运行doctoc命令以生成和更新目录。

执行doctoc demo.md,即可为demo.md文件在文档中自动生成目录:
npm语法生成.jpg

效果:
npm语法生成-2.jpg

markdown-toc

全局安装doctoc:

npm install -g markdown-toc

与doctoc不同的是,markdown-toc 工具会将目录插入到文件中包含<!-- toc --> 标记的位置。并且markdown-toc默认不自动将目录注入到文件中,需要加入参数-i

markdown-toc -i demo.md

结语

本文主要介绍了Markdown生成目录的几种技巧,目录少的时候可以手动生成,目录多的时候需要借助工具生成。大部分Markdown编辑器支持[TOC]语法的方式,推荐大家使用这种语法方式一键生成。当然你也可以选择npm命令行的形式执行,让目录在文件中可视化,更具有可读性。