前言
在 Web 开发中，Markdown 已变得越来越流行。通常情况下，在撰写大型文档时会需要使用到目录。那么开发者们通过 gulp 和 npm 包生态创建了一个轻松的方式，来为 Markdown 文件创建目录。本篇文章将介绍这个 npm 包 — gulp-markdown-toc 的使用方法。
简介
gulp-markdown-toc 插件可以为 Markdown 文档生成目录，并且可以递归地遍历目录结构。其最好的特性就在于它使用 Lucid.js 作为解析器。通过 Lucid.js，它清洁，非常快速，且具有公共标记解析。gulp-markdown-toc 使得为 Markdown 文件创建目录变得更加便捷。
安装
通过 cmd 命令行进入项目所在目录，运行如下命令进行安装：
npm install gulp-markdown-toc --save-dev
用法
以下是一个简单的 Gulp 任务，它使用 gulp-markdown-toc 来为 Markdown 文件生成目录：
-- -------------------- ---- -------
----- ---- - ----------------
----- ----------- - -----------------------------
---------------- -----------
------ -------------------------
-------------------
-- -------
---
--------------------------
---上述代码首先载入 npm 包，接着运行名为 toc 的 Gulp 任务，该任务通过函数实现。函数使用了 gulp.src 和 pipe 方法来获得 markdown 文件并通过 gulp-markdown-toc 插件进行处理。
教程
而 options 则会接受一个配置对象，其可以具有以下属性：
- headers: 可以是一串要在目录中搜索的标题，例如： 'h2' 或 'h2,h3'。默认情况下，该属性设置为 'h2'。
- noFirstH1: 一个布尔值，如果为 true，则会从 h2 处开始构建目录并使用文档的第一 h1 标题为最高级标题。 默认值为 false。
- noAnchor:一个布尔值，如果为 true，则不会为标题提供锚链接到相同的文件中的其他位置。需要提醒的是，为没有ID的标题产生的一个独一无二的锚链接，故默认为 false。
- updateContent: 一个布尔值，如果为 true，则会为每个 Markdown 文件更新目录。如果为 false，则会禁止更新并且只建立表格。 默认值为 true。
- bullets: String or function，如果是一个字符串，它会被用作目录项的符号。否则该函数会接收一个level参数，该级别对应每个 toc 中的标头级别，并且需要返回该层级别的目录项符号。
示例代码
以下是一个最小化的用例示例:
# gulp-markdown-toc ## Usage ### 1. Install package ```sh npm install gulp-markdown-toc --save-dev
2. Require plugin
const markdownToc = require('gulp-markdown-toc');3. Add Gulp Task
gulp.task('toc', function(){
return gulp.src('./src/**/*.md')
.pipe(markdownToc({
// options
}))
.pipe(gulp.dest('./src'));
});每个 markdown 文件都应有一个目录。 在我们的例子中，它是第二个标题级别。 让我们看看我们如何为特定级别创建目录符号（bullet-symbol）：
-- -------------------- ---- -------
---------------- -----------
------ -------------------------
-------------------
-------- --------------- -
-------- -- -- -
------ ----
-
---- -
------ ----
-
-
---
--------------------------
---通过使用 bullets 选项，我们可以定义特定级别的符号。 例如，如果我们想在二级标题（h2）中使用破折号作为符号，则会在 options 对象传递一个函数。 这个函数会被执行，并且会对当前遍历的标题级别中存在的每一个标题（ h2 的第二个标题）
指导意义
简要地说，gulp-markdown-toc 插件可以让我们轻松创建出美观且逻辑性强的 Markdown 文件。本篇文章展示了该插件的基本用法，并提供了示例代码，深入阐述了其选项的用处。使用 gulp 和 npm 包生态系统，该插件为前端开发者提供了一个快速实现功能的工具。其意义不仅在于帮助我们提高开发效率，而且可让我们的文档更加规范和容易理解。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60055d1d81e8991b448daba5