在开发前端应用程序时，API 文档是必不可少的。然而，随着 API 文档内容的增加，很容易失去对整个文档的概览和结构的掌控。这时候，一个自动生成目录的工具将会显得尤为重要。

npm 包 api-toc 就是这样的一个工具，它可以自动扫描 Markdown 格式的 API 文档，生成一个包含所有函数、类、方法等内容的目录，并且可以嵌入到文档中。

安装

在终端中运行以下命令，安装 api-toc：

npm install -g api-toc

使用

命令行使用

在终端中进入 API 文档所在的目录，输入以下命令：

api-toc -i README.md -o toc.md

其中，-i 参数指定输入文件，-o 参数指定输出文件。这条命令将在当前目录下生成一个名为 toc.md 的文件，其中包含了 API 文档的目录。

在代码中使用

如果你想在你的代码中使用 api-toc，可以通过以下方式来实现：

const fs = require('fs');
const apiToc = require('api-toc');

const input = fs.readFileSync('./README.md', 'utf8');
const output = apiToc(input);

fs.writeFileSync('./toc.md', output);

在这个例子中，我们首先使用 fs 模块读取了 API 文档的 Markdown 内容，然后将其传递给了 apiToc 函数。最后，我们将生成的目录内容写入到了名为 toc.md 的文件中。

示例代码

假设我们有一个包含以下 Markdown 内容的 API 文档：

-- -------------------- ---- -------
- -- ---

-- ------- ---

--------

--- --

- ----------
- ----------

--- ---

------

-- --------------

------------

--- --

- ---------------

--- ---

----------

输入以下命令可以生成一个目录，并且将其嵌入到文档中：

api-toc -i README.md -o toc.md --embed

生成的目录如下所示：

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

## `sum(a, b)`
...
## `max(numbers)`
...

你可以将这段目录代码复制粘贴到 Markdown 文件的任何位置，它会被自动解析为一个目录。例如，将其插入到标题下方：

# My API

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

## `sum(a, b)`

...

最终效果如下所示：

My API

sum(a, b)

...

这样做可以使你更加方便地查找和导航文档中的内容，提高开发效率。

总结

api-toc 是一个非常实用的工具，它可以帮助我们自动生成神经病般的 API 文档目录，并且可以嵌入到 Markdown 文件中。使用 api-toc 可以大大提高阅读和编写 API 文档的效率，推荐给所有前端开发者使用。

来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/46992