Foreword
在 Markdown：写技术文档、个人博客和读书笔记都很好用的轻量级标记语言这篇文章中，给大家介绍了 Markdown 及其创始人的故事、Markdown 基本语法、常见的 Markdown 编辑器（Mac/Windows 平台和在线编辑器）。
新接触 Markdown 的小伙伴建议先戳那篇文章去补充点能量，已熟悉 Markdown 的小伙伴可以速往下看。
在使用 Markdown 写文档时，有时需要给单个文档生成目录，比如包含多个问题的 FAQ (Frequently Asked Questions) 文档。
那么，如何为 Markdown 文件（即 .md 格式的文件）自动生成目录呢？下面给大家介绍两种方法：
- Visual Studio Code + Markdown TOC 扩展
- Pandoc 命令
1. Visual Studio Code + TOC 扩展
Visual Studio Code (VS Code) 是一个由微软开发的，同时支持 Windows、Linux 和 macOS 操作系统的开源文本编辑器。它支持调试，内置了 Git 版本控制功能，同时也具有开发环境功能，例如代码补全、代码片段、代码重构等。
如果你对 VS Code 的图标感兴趣，可以参考这篇文章：The Icon Journey
VS Code 编辑器支持用户自定义配置，例如改变主题颜色、键盘快捷方式、编辑器属性和其他参数。另外，还支持扩展程序，并在编辑器中内置了扩展程序管理的功能。
到底如何使用 VS Code + TOC 扩展为 Markdown 文件自动生成目录呢？具体操作步骤如下：
1. 下载和安装 Visual Studio Code。
下载地址：https://code.visualstudio.com/download
安装成功后，双击图标打开，显示如下：
2. 单击 VS Code 的扩展图标，在搜索框搜索 Markdown TOC 并安装。
此扩展长这样：
安装成功后，点击左侧扩展图标，可查看已安装的扩展。如下图所示：
3. 点击菜单栏的文件 -> 打开，打开需要生成目录的 .md 格式的文件。
以如下 FAQ.md 文件为例：
FAQ.md 在 VS Code 中打开后显示如下：
4. 将光标移至需要插入目录的位置，右键单击 Markdown TOC: Insert/Update [^M T]，目录即自动插入。
显示效果如下：
5. 单击右上角的预览图标，可查看目录的显示效果。
显示效果如下：
注：为保持文档整洁，删除目录首尾的如下字符：
<!-- TOC -->
<!-- /TOC -->
6. 保存，关闭文件。
2. Pandoc 命令
Pandoc 是由 John MacFarlane 开发的标记语言转换工具，可实现不同标记语言间的格式转换，堪称该领域中的“瑞士军刀”。Pandoc 使用 Haskell 语言编写，以命令行形式实现与用户的交互，可支持多种操作系统。
如何使用 pandoc 命令为 Markdown 文件自动生成目录呢？仍以 FAQ.md 文件为例，具体操作步骤如下：
1. 下载和安装 pandoc。
下载地址：https://github.com/jgm/pandoc/releases
关于安装，可参考：https://pandoc.org/installing.html
2. 打开终端，输入 pandoc --version 确认 pandoc 已成功安装。
此命令返回结果如下图所示：
3. 依次使用以下命令，转到 FAQ.md 文件所在的目录。
-
pwd：查看查看当前目录路径，“printing working directory” 的缩写。 -
ls：查看目录列表，“list segment” 的缩写。 -
cd：转到某目录下，是 “change directory” 的缩写。
具体使用举例：
或者，如果你清楚地知道文档所在目录，可以使用如下简化的操作：
详细的使用说明可参阅：https://pandoc.org/getting-started.html#step-3-changing-directories
4. 输入以下命令，即可自动生成目录。
pandoc -s --toc --toc-depth=4 FAQ.md -o FAQ.md
注：pandoc 默认生成三级目录。以上述命令为例，如果使用如下命令则只会生成三级目录：
pandoc -s --toc FAQ.md -o FAQ.md
而我想让 FAQ.md 这篇文档生成四级目录，所以加了个参数 --toc-depth，并将其值设置为 4。大家可根据具体需求进行设置。
5. 打开 .md 文档，查看目录。
命令已成功为 FAQ.md 文件生成了目录，显示如下：
如果你想了解 pandoc 的更多功能和参数使用，可参考 pandoc 官网的文档：https://pandoc.org/MANUAL.html
Afterword
以上两种方法，我更常用的是 Visual Studio Code 中的 Markdown TOC 扩展，因为操作起来既方便又直观。有需求的小伙伴赶快试一试吧！
你可能想读：
书单 | 有哪些技术传播从业者必知必看的书籍？
有哪些适合技术传播从业者关注的优质博客？
Markdown：写技术文档、个人博客和读书笔记都很好用的轻量级标记语言
技术写作实例解析 | 简洁即是美
两分钟趣味解读 Technical Writer
若脱离理解，直译得再正确又有何意？
优质译文不应止于正确，还要 Well-Organized
写在入职技术型创业公司 PingCAP 一个月之后
-END-
