在前端开发过程中，文档的编写和维护是非常重要的。而 documentalist 就是一款能够快速生成文档的 npm 包，特别适合用来为一些开源项目编写文档。本篇文章将介绍 documentalist 的使用教程，希望能够帮助到前端开发者。
安装
documentalist 是一个 npm 包，因此通过 npm 安装即可：
--- ------- -- -------------
使用
创建一个项目
在使用 documentalist 之前，首先需要在本地创建一个项目。以一个名为 my-project 的项目为例，可以使用以下命令创建：
----- ---------- -- -- ---------- --- ----
安装必要的依赖
在 my-project 项目中，我们需要安装必要的依赖，以便能够使用 documentalist。具体的依赖，包括 documentalist 本身和用于转换 markdown 文档的 markdown-it。
--- ------- ------ ------------- -----------
编写文档
documentalist 使用 markdown 格式编写文档。因此我们需要在 my-project 项目中创建一个文档文件夹，并在里面编写 markdown 文档。例如，我们在 my-project 中创建了一个名为 docs 的文件夹，并在其中编写了一个名为 getting-started.md 的文档：
----- ---- -- -- ---- ---- -- ------- -------- - ------------------
生成文档
完成以上步骤后，我们可以使用 documentalist 来生成文档了。在 my-project 项目目录下，使用以下命令即可：
------------- -- ---- -- ----------
其中：
-i docs参数表示文档源目录，即上一步中创建的 docs 目录。-o docs/_site参数表示生成的静态网站目录，即文档输出目录。
预览文档
当生成了文档后，我们可以使用 http-server 等工具来预览文档。例如，在 my-project 中安装 http-server：
--- ------- ---------- -----------
然后，在文档输出目录 docs/_site 中启动 http-server：
-- ---------- -----------
最后，在浏览器中输入 http://localhost:8080，即可预览文档了。
示例代码
为了更直观地说明 documentalist 的使用过程，以下是一个基于 Vue.js 创建的 my-project 示例代码：
---------------------------- - --------- ------------ ------------- --
创建文档：在上述示例代码中，我们创建了一个名为 hello-world 的组件。为了方便其他开发者查看和使用该组件，我们需要编写相应的文档。在 my-project 的 docs 目录下，创建一个名为 components.md 的文件，并在其中编写文档：
- --- -- ----------- ---- ------- ------- ---- --- -- ---- -- ------- ---------------------------
API
暂无。
----------------------------
documentalist -i docs -o docs/_site
--------- ---------- ----- ------------
cd docs/_site http-server
------- ------------------------------------------------------ -- -- ---------------- ------------- ------------- --- ------------------------------- ------------- ---------------------------- ------------------------------------------------------------------------------ ---------- -----------------------------------------------------------------------------------------------------------------------------