在前端开发中，我们经常需要编写文档以及 API 文档，而 documentation-markdown-api-theme 是一个非常优秀的 npm 包，可以实现自动生成 API 文档并可以定制主题样式，这对于开发者来说非常方便。
什么是 documentation-markdown-api-theme？
documentation-markdown-api-theme 是一个基于 documentation.js 的 API 文档生成工具，可以将 jsdoc 样式注释转换成美观的 Markdown 或者 HTML 格式的 API 文档，并且支持自定义主题样式，使得 API 文档更加美观和易读。
documentation-markdown-api-theme 安装
在使用 documentation-markdown-api-theme 之前，我们需要先安装它：
npm install documentation-markdown-api-theme --save-dev
安装完成后，我们就可以开始使用这个 npm 包了。
使用教程
接下来，我们展示如何使用 documentation-markdown-api-theme 来生成自定义主题样式的 API 文档。
1. 配置文件
我们需要新建一个 documentation.json 配置文件，来配置我们需要生成的 API 文档，同时也包含主题样式。
-- -------------------- ---- -------
-
--------- -
-------- --- ------- --- ---------------
-------- -----------------------------------
----------- -
------ ----
--
--------- -
------------- ------------
-
--
--------- -
----------------- -------------------
----------------- ----------------
---------- -
-------
-
--
---------- -
------------------
--
----------- -
--------------- ----
-
-config.title：指定 API 文档的标题。config.theme：指定使用的主题样式。config.markdown：指定 Markdown 的配置，这里使用了一个自动生成的目录。config.styles.stylesheet：指定自定义样式的样式表。source.includePattern：指定项目中需要包含的源码路径。source.excludePattern：指定项目中需要排除的源码路径。source.include：指定源码路径，这里使用模块化方式，可以添加多个。plugins：指定生成文档的插件，这里使用了 markdown 插件。markdown.idInHeadings：指定是否在标题中包含 ID。
2. 样式表
我们需要在项目中新建一个样式表，来定义 API 文档的样式。
-- -------------------- ---- ------- -- ------ -- ------ - ---------- ----- ------------ ----- ----------- ------- ----------- ----- - -- ----- -- -------- -- ---- - ---------- ----- ------------ ----- - -- ------- ----- -- --------------- - ---------- ----- ------------ ----- ----------- ----- - -- ------ ------- -- ------------- -------------- - ---------- ----- ------------ ----- - -- ------ ----------- -- ------------------- - ---------- ----- -
3. 命令行
我们可以使用以下命令生成 API 文档：
npx documentation readme ./src/*.js -f md -o ./docs --config documentation.json
命令解释：
npx documentation：使用 documentation 包。readme：指定需要生成的 README 文件，这里使用源码文件。./src/*.js：指定读取的源码文件路径。-f md：指定生成的格式为 Markdown。-o ./docs：指定生成文档的输出路径。--config documentation.json：指定使用的配置文件。
4. 生成效果
通过以上步骤，我们就可以生成一份自定义主题样式的 API 文档。
以下是样式效果的部分截图：
总结
documentation-markdown-api-theme 是一个非常优秀的 npm 包，可以让我们方便的生成美观且易读的 API 文档，并支持自定义主题，使得文档更具有可读性与可维护性。这篇文章介绍了使用这个工具的所有必要步骤，想要使用该工具的读者们可以进行尝试并参考本文中的配置文件和样式表，定制自己项目的 API 文档。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/72122