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