前言
在前端开发过程中，我们经常需要生成文档来记录我们的工作成果，对于一些技术文档而言，AsciiDoc 是一种非常好的文档格式。在这篇文章中，我们会介绍一个 npm 包 - broccoli-asciidoc，来帮助我们快速生成 AsciiDoc 格式的文档。
什么是 broccoli-asciidoc
broccoli-asciidoc 是一个基于 broccoli 的命令行工具，用于将一个 AsciiDoc 文件编译生成 HTML 或者 PDF 格式的文档。
broccoli 是一个用于构建前端项目的构建工具，它的主要特点是可以使用 Node.js 编写构建插件的能力，使得构建流程更加灵活和易于扩展。
broccoli-asciidoc 安装
在本地安装 broccoli-asciidoc 很简单，只需要使用 npm 工具即可：
npm install broccoli-asciidoc --save-dev
安装完成后，我们需要在项目根目录添加一个 broccoli.js 配置文件。在这个文件中，我们可以使用 broccoli-asciidoc 提供的工具来完成对 AsciiDoc 文件的构建：
-- -------------------- ---- -------
----- -------- - -----------------------------
----- --------- - ------------------------------
----- ------------ - -----------------------------
----- ------- - -
----------- -
---------- ---------
-------- -------
------------ -------
--------------------- -------------
--
----- -------
-------- --------
-------- ---------
--
-------------- - ------------------- ------------- ---------在上面的代码中，我们首先引入 broccoli-asciidoc 包，然后在配置文件中定义输入和输出路径，之后进行一些编译选项的配置。最后，我们导出了一个 asciidoc 函数，使用它来完成对 AsciiDoc 文件的构建。
broccoli-asciidoc 使用方法
有了上面的配置文件，我们可以使用 broccoli 命令来启动构建工具：
broccoli serve
这个命令会在本地启动一个静态服务器，提供一个访问地址。我们可以在浏览器中访问这个地址，来查看生成的 HTML 格式文档。
如果希望生成 PDF 格式文档，我们需要安装 wkhtmltopdf 工具，并且把 backend 配置项设置为 pdf。在这里，我们推荐使用 docker 环境来安装 wkhtmltopdf 工具，这样可以减少对本地环境的依赖。
以下是一些示例代码，供大家参考：
编写 AsciiDoc 文件
在项目目录中创建一个 .adoc 文件，然后在文件中编写文档内容。例如，我们可以编写一个简单的 hello-world.adoc 文件：
= Hello World Welcome to our new project!
在 broccoli 配置文件中配置 Asciidoc 编译过程
在项目根目录下创建一个 broccoli.js 文件，然后在文件中进行配置。以下是一份示例代码：
-- -------------------- ---- -------
----- -------- - -----------------------------
----- ---------- - --------------------------------
----- ------ - ---------------------------
----- ---- - ----------------
----- --------- - ------------------
----- ------------ - ---------
----- ------- - -
----------- -
---------- ---------
-------- -------
------------ -------
--------------------- -------------
--
----- -------
-------- --------
-------- ---------
--
----- -------- - --- ----------------- -
-------- ----------
---
----- -------- - ------------------ -
------------ ---------------
------------- -------
-------- -------
---
----- ------- - ------------------ -
------------ --------------
------------- ------
-------- ----------------- -------- - -------- ----- --
---
----- --------- - --- --------------------- ----------
-------------- - ----------在上面的代码中，我们使用 Funnel 插件将 asciidoc 文件拷贝到输出目录中，然后编写一个 asciidoc 构建函数，并提供一些编译选项。这个函数会生成一个 HTML 文件和一个 PDF 文件，并将它们合并到同一个目录中。
运行构建工具
启动构建工具十分简单，输入以下命令即可：
broccoli serve
构建完成后，我们就可以在浏览器中访问生成的文件。
小结
在这篇文章中，我们介绍了一个 npm 包 - broccoli-asciidoc，它可以帮助我们在前端开发过程中快速生成 AsciiDoc 格式的文档。我们先介绍了 broccoli 和 broccoli-asciidoc 的相关概念，并讲解了它们的安装和使用方法。之后，我们提供了一些示例代码，希望可以帮助大家更好地学习和使用这个 npm 包。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60066c8accdc64669dde5258