在前端开发中，我们经常需要编写文档来记录项目的使用说明和技术细节。手动编写文档是十分繁琐而且容易出错的，所以自动化生成文档就显得非常重要。本文介绍的 npm 包 @igorkling/gendoc 就是一款可以用来自动生成文档的工具。
简介
@igorkling/gendoc 是一款基于 Markdown 的自动生成文档工具，它可以把 Markdown 文件转成 HTML 和 PDF 格式的文档，并且支持模板定制。它使用极其简单，只需要在 Markdown 文件中添加一些特殊的注释，就可以定制文档的目录结构和文档元素。同时，它也支持命令行参数设置，可以自定义文档的输出格式和样式。
安装
前提是你已经成功安装了 Node.js 和 npm。在命令行中运行下面的命令即可安装 @igorkling/gendoc：
npm install -g @igorkling/gendoc
使用
基本用法
使用 @igorkling/gendoc 非常简单，只需要在 Markdown 文件中添加注释，然后在命令行中输入 gendoc 命令，就可以生成对应的文档。
首先，我们需要在 Markdown 文件中添加目录和标题的注释。下面是一个示例：
-- -------------------- ---- ------- - -- ------- ---- --- --- - ----------------------------- - ----------------------------- - --------------- - --------------------- - ----------- - ----------------------------- - ------------------- ---- ---- --- -- ------------ ---- -- --- ------------- -- ------------ ---- -- --- ------------ -------- -- ----- ---- -- --- ----- -------- --- -------- ---- -- --- -------- -------- -- --- ---- -- --- --- -------- -- ------------ ---- -- --- ------------ -------- -- ------- ---- -- --- ------- --------
在 Markdown 文件中添加 和 注释即可生成目录。然后，我们需要在标题下方添加对应的注释，例如：
## Introduction This is the introduction. <!-- START_DESCRIBE --> Here we describe the introduction. <!-- END_DESCRIBE -->
这段代码表示的是在生成的文档中，对应章节的描述文本。
最后，在命令行中运行下面的命令即可生成文档：
gendoc myproject.md
这样就可以在当前目录下生成 myproject.html 和 myproject.pdf 两个文件。可以通过命令行选项来自定义输出格式，例如：
gendoc myproject.md --format html
高级用法
@igorkling/gendoc 还支持很多高级用法，例如自定义模板、自定义样式和自定义标题等。这里给出一些示例：
自定义模板
@igorkling/gendoc 内置了两种模板，分别是 default 和 plain。如果你想自定义模板，可以使用命令行选项 --template 指定自己的模板文件，例如：
gendoc myproject.md --template mytemplate.hbs
在 mytemplate.hbs 文件中可以使用 Handlebars 模板引擎语法来定义模板。可以参考 @igorkling/gendoc 官方文档来学习更多模板相关内容。
自定义样式
@igorkling/gendoc 生成的文档默认使用 Github 风格的样式，如果你想使用自己的样式，可以使用命令行选项 --style 指定样式文件，例如：
gendoc myproject.md --style mystyle.css
自定义标题
默认情况下，@igorkling/gendoc 使用 Markdown 文件的第一个标题作为文档的标题。如果你想使用自己的标题，可以使用命令行选项 --title 指定标题，例如：
gendoc myproject.md --title "My Custom Title"
结语
@igorkling/gendoc 是一款非常实用的自动生成文档工具，尤其适用于大型项目和多人协作。通过本文的介绍，相信大家已经对它有了一个初步的了解，并可以快速上手使用。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60066b5451ab1864dac669c6