markdown添加目录

img

Foreword

Markdown:写技术文档、个人博客和读书笔记都很好用的轻量级标记语言这篇文章中,给大家介绍了 Markdown 及其创始人的故事、Markdown 基本语法、常见的 Markdown 编辑器(Mac/Windows 平台和在线编辑器)。

新接触 Markdown 的小伙伴建议先戳那篇文章去补充点能量,已熟悉 Markdown 的小伙伴可以速往下看。

在使用 Markdown 写文档时,有时需要给单个文档生成目录,比如包含多个问题的 FAQ (Frequently Asked Questions) 文档。

那么,如何为 Markdown 文件(即 .md 格式的文件)自动生成目录呢?下面给大家介绍两种方法:

  • Visual Studio Code + Markdown TOC 扩展
  • Pandoc 命令

Visual Studio Code + TOC 扩展

Visual Studio Code (VS Code) 是一个由微软开发的,同时支持 Windows、Linux 和 macOS 操作系统的开源文本编辑器。它支持调试,内置了 Git 版本控制功能,同时也具有开发环境功能,例如代码补全、代码片段、代码重构等。

img

如果你对 VS Code 的图标感兴趣,可以参考这篇文章:The Icon Journey

VS Code 编辑器支持用户自定义配置,例如改变主题颜色、键盘快捷方式、编辑器属性和其他参数。另外,还支持扩展程序,并在编辑器中内置了扩展程序管理的功能。

img

VS Code 支持的扩展

到底如何使用 VS Code + TOC 扩展为 Markdown 文件自动生成目录呢?具体操作步骤如下:

1. 下载和安装 Visual Studio Code。

下载地址:https://code.visualstudio.com/download

img

安装成功后,双击图标打开,显示如下:

img

2. 单击 VS Code 的扩展图标,在搜索框搜索 Markdown TOC 并安装。

img

VS Code-extension-icon

此扩展长这样:

img

安装成功后,点击左侧扩展图标,可查看已安装的扩展。如下图所示:

img

3. 点击菜单栏的文件 -> 打开,打开需要生成目录的 .md 格式的文件。

以如下 FAQ.md 文件为例:

img

在 MacDown 中的显示

FAQ.md 在 VS Code 中打开后显示如下:

img

4. 将光标移至需要插入目录的位置,右键单击 Markdown TOC: Insert/Update [^M T],目录即自动插入。

img

显示效果如下:

img

5. 单击右上角的预览图标,可查看目录的显示效果。

img

预览图标

显示效果如下:

img

:为保持文档整洁,删除目录首尾的如下字符:

1
2
<!-- TOC -->
<!-- /TOC -->

6. 保存,关闭文件。

npm 语法生成

全局安装doctoc插件

1
npm i doctoc -g //install 简写 i

假如你的markdown文件在work/demo.md文件下,只需要cd work 切换到当前文件目录下,执行doctoc demo.md文件,即可在文档中自动生成目录。

img

doctoc

Pandoc 命令

Pandoc 是由 John MacFarlane 开发的标记语言转换工具,可实现不同标记语言间的格式转换,堪称该领域中的“瑞士军刀”。Pandoc 使用 Haskell 语言编写,以命令行形式实现与用户的交互,可支持多种操作系统。

如何使用 pandoc 命令为 Markdown 文件自动生成目录呢?仍以 FAQ.md 文件为例,具体操作步骤如下:

1. 下载和安装 pandoc。

下载地址:https://github.com/jgm/pandoc/releases

img

关于安装,可参考:https://pandoc.org/installing.html

2. 打开终端,输入 pandoc --version 确认 pandoc 已成功安装。

此命令返回结果如下图所示:

img

3. 依次使用以下命令,转到 FAQ.md 文件所在的目录。

  • pwd:查看查看当前目录路径,“printing working directory” 的缩写。
  • ls:查看目录列表,“list segment” 的缩写。
  • cd:转到某目录下,是 “change directory” 的缩写。

具体使用举例:

img

或者,如果你清楚地知道文档所在目录,可以使用如下简化的操作:

img

详细的使用说明可参阅:https://pandoc.org/getting-started.html#step-3-changing-directories

4. 输入以下命令,即可自动生成目录。

1
pandoc -s --toc --toc-depth=4 FAQ.md -o FAQ.md

:pandoc 默认生成三级目录。以上述命令为例,如果使用如下命令则只会生成三级目录:

1
pandoc -s --toc FAQ.md -o FAQ.md

而我想让 FAQ.md 这篇文档生成四级目录,所以加了个参数 --toc-depth,并将其值设置为 4。大家可根据具体需求进行设置。

5. 打开 .md 文档,查看目录。

命令已成功为 FAQ.md 文件生成了目录,显示如下:

img

img

如果你想了解 pandoc 的更多功能和参数使用,可参考 pandoc 官网的文档:https://pandoc.org/MANUAL.html

Afterword

以上两种方法,我更常用的是 Visual Studio Code 中的 Markdown TOC 扩展,因为操作起来既方便又直观。有需求的小伙伴赶快试一试吧!

本文原创,商业转载请联系作者获得授权,非商业转载请注明出处。

评论

发送评论 编辑评论


                        

待分类分类热门文章

标签热门文章排行

☛免责声明 ☛本站使用教程
Theme Argon With Ry-Plus By 清欢
我的第15740位朋友,历经88317次回眸才与你相遇