在前端开发中，我们经常需要生成文档来说明项目的结构和使用方法。而在生成文档过程中，一些较长的文档可能需要添加目录来提高文档的阅读体验和可用性。本文将介绍一款方便的工具 metalsmith-doctoc，并说明其使用方法。
metalsmith-doctoc 是什么？
metalsmith-doctoc 是一个基于 Node.js 平台的 metalsmith 插件。该插件可以使用 GitHub 的目录生成工具 doctoc 来自动生成文档的目录结构，并将其集成到任意 metalsmith 包中。metalsmith-doctoc 还可以为目录添加默认选项，如添加链接、最大展开层数等。
metalsmith-doctoc 的安装
要使用 metalsmith-doctoc，需要先安装 Node.js 和 metalsmith (全局安装或在项目中安装)。同时，还需要在 Node.js 模块管理器 npm 中安装 metalsmith-doctoc 插件。
安装命令如下：
npm install --save metalsmith-doctoc
metalsmith-doctoc 的使用
在集成 metalsmith-doctoc 插件到 metalsmith 构建流程中之前，需要首先在 Markdown 源文件中添加要生成目录的标记。metalsmith-doctoc 可以通过查找 Markdown 源文件中的标记来自动生成目录。
这里以 Markdown 文档的表格为例，假设 Markdown 文档的内容如下：
# 表格演示 | a | b | c | | --------- | --------- | --------- | | 1 | 2 | 3 | | 4 | 5 | 6 | | 7 | 8 | 9 |
在该 Markdown 文档中，我们希望为这个表格添加目录。可以在表格的上方添加 doctoc 标记来实现。
<!-- doctoc --> # 表格演示 | a | b | c | | --------- | --------- | --------- | | 1 | 2 | 3 | | 4 | 5 | 6 | | 7 | 8 | 9 |
添加了 doctoc 标记之后，接着在 metalsmith 的构建流程中引入 metalsmith-doctoc 插件并进行配置，就可以实现自动生成目录。
以下是创建一个米构建流程并加入 metalsmith-doctoc 插件的示例代码：
-- -------------------- ---- -------
--- ---------- - ----------------------
--- ------ - -----------------------------
---------------------
--------------
---------------------
-------------
-------- -
----- ---------
--------- -
--
--------- -------
---
-------------------- -
-- ----- ----- ----
---在上述代码中，首先通过 require 引入 metalsmith 和 metalsmith-doctoc 库。然后使用 Metalsmith 方法创建一个新的 Metalsmith 实例，并进行源目录和目标目录的设置。接着使用 .use 进行插件配置。在插件配置中，我们可以设置多个选项，如自动生成目录的最大展开层数、链接是否为锚点等。上述代码中，selector 属性可选，如果设置了 selector，目录将只会处理设置的元素。
在构建流程中，.use(doctoc({...})) 方法将 metalsmith-doctoc 插件添加到 metalsmith 的构建流程中，并使用设置选项进行配置。当 metalsmith 进行构建时，metalsmith-doctoc 插件将为每个包含 doctoc 标记的源文件自动生成目录，并将结果保存到目标目录中。
总结
通过整理上述内容，我们了解了 metalsmith-doctoc 插件的主要作用和使用方法。metalsmith-doctoc 拥有丰富的选项和灵活的配置，可以帮助我们轻松地生成 Markdown 目录，提高文档的可读性和可用性。如果您使用 Metalsmith 进行文档构建，metalsmith-doctoc 可能是一个很好的选择。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/600559d981e8991b448d75b2