前言
文档对于任何一个项目来说都是非常重要的一部分，特别是对于开源项目来说更加重要。因为没有足够的文档，很难让其他人知道这个项目的使用方法以及原理，并且也难以让其他贡献者更好地参与到这个项目中来。
而随着前端技术的不断发展，现在的前端项目也越来越依赖于各种 npm 包。这些 npm 包可以帮助我们完成各种各样的任务，比如构建、测试、打包等等。同时，也有很多 npm 包专门用于生成文档，比如这篇文章要介绍的 npm 包 documentation-theme-bespoke。
documentation-theme-bespoke 是一个基于 Bespoke.js 的文档主题，可以非常方便地生成漂亮的文档。本文就来详细介绍一下 documentation-theme-bespoke 的使用方法，并附上示例代码。
安装
首先，我们需要先安装 documentation-theme-bespoke，可以使用 npm 来便捷安装：
npm install documentation documentation-theme-bespoke
其中 documentation 是一个生成文档的工具，也是 documentation-theme-bespoke 的官方推荐工具。
配置
安装完毕之后，我们需要配置一些选项来生成我们需要的文档。打开 package.json 文件，然后添加如下配置：
-- -------------------- ---- -------
-
------- ------------
---------- --------
---------- -
------- -------------- ----- -------- -- ---- -- --------- -- ------------- -- -- --------- -- ---------------------------------------- -------- -- ----------
--
--------------- -
---------------- ----------
------------------------------ --------
-
-我们需要配置 docs 指令，这个指令会帮我们生成文档文件。documentation 会生成 json 文件，documentation-theme-bespoke 会根据这个 json 文件生成我们最终需要的 html 文件。
这里需要注意的是，docs 指令中的 index.js 和 index.md 分别是我们库的入口文件和文档的入口文件，你需要将这两个文件名换成你实际项目中的文件名。
除此之外，我们还需要在项目根目录下创建一个 .documentation.yml 文件，里面内容如下：
-- -------------------- ---- -------
-------
------- ----
----- ---------
--------
- ----- --------------------------------------------------
--------
---------------- -----
---------- ----
------------------ ---------------- - ---------
------
--------
- ---
--------
- ----------------------------
- ----------------------------
----------- ----
--------
------ ---------------------
--------
- ------------
- -------------
- -------------
- ---------------
- ------------
- ----------------
- ---------------这个文件的作用是，告诉 documentation 要使用 documentation-theme-bespoke 这个主题来生成文档，以及一些其他一些配置，比如幻灯片的样式、babel 的配置等等。
写文档
所有的配置完成之后，我们可以正式开始写文档了。在项目根目录下创建一个 index.md 文件，然后开始书写自己的文档。
这里需要注意的是，文档的格式需要遵循 commonmark 的规范，每一篇文档中的代码都需要在 ``` 代码块中标注语言，比如：
// 示例代码
function sum(a, b) {
return a + b
}当文档的内容写完之后，我们可以使用上面在 package.json 中配置好的 docs 指令来生成我们最终需要的文档。
npm run docs
文档文件会被生成在项目目录下的 docs.html 文件中。
结尾
通过使用 documentation-theme-bespoke，我们可以快速便捷地生成漂亮的文档，这有助于我们更好地管理自己的项目，并且更好地与其他人进行沟通交流。
当然，本文只是一个简单的教程，更多的使用方法和功能请查看 官方文档。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5eedad19b5cbfe1ea0610bd6