在前端开发中，文档化开发已经成为一种通行的开发范式，来帮助我们更好地管理我们的代码和文档。但是，写文档也是一项技能，书写过程有时候会十分繁琐乏味。而 npm 包中也有一款非常优秀的文档工具 docz，其可以帮助我们开发出富有交互性及可阅读性的组件文档。
*本文：将会指导你学会如何使用 npm 包 docz 来生成我们的组件文档。
1. 什么是 docz
docz 是一款使用 react 进行开发的、能够帮助我们更加方便地管理组件库文档的工具，其其提供了一键式生成页面的能力，并且带有相应的样式。
2. 使用 docz
接下来咱们一起来了解如何使用 docz，一些简单的操作和配置都将会在以下内容中介绍：
2.1 安装 docz
docz 可以通过 npm 来进行安装:
npm i docz --save-dev
2.2 创建一个 docz 应用
在这里我将创建一个名为「docz-learning」的文档项目，并将它写在 ~/projects/docz-learning 目录中:
cd ~/projects mkdir docz-learning cd docz-learning
接下来需要在当前目录执行以下代码，用于创建并开启一个新的 docz 应用：
yarn init -y && yarn add react react-dom docz
执行完这个之后，在 package.json 中添加如下内容，以便在执行以下代码的时候可以顺利地执行例子：
"scripts": {
"docz:dev": "docz dev",
"docz:build": "docz build"
}2.3- 排列你的目录结构
docz 是一个对目标文档作为「源头」来进行进行开发的工具，所以在使用 docz 之前，你需要为构建的文档进行一定的规范和排列工作。我们可以使用下面目录结构：
-- -------------------- ---- -------
--------
--- ---------
--- ---------
--- ------------
--- ---
- --- ----------
- - --- ------
- - --- ------
- - --- -----
- - --- ---------
- --- -----
- - --- -------------------
- - --- ----------
- - --- ----------
- - --- ----------
- --- ---------
--- ------
--- ---------这里为了做简化就没有使用任何样式的文件。
2.4 学习 MDX
在 docz 中，Markdown 仍然会是我们目标编写语言，不过我们可以稍微升级它来进行实现一些更加复杂的介绍和展示方式。因此 docusaurus 选用了一门名叫做 MDX 的语言来进行进行这样的操作。文档中不仅可以有 Markdown，也可以有 React 组件。
在这里是一些介绍，用于介绍 MDX 中如何编写组件：
在 MDX 中，使用 JSX 的方式来创建组件，并且还支持了自定义组件。下面是简单的自定义组件的例子：
-- -------------------- ---- ------- ------ - ---- - ---- -------------------- - --- ------- ------- ---- -- - ---- ---------- ---- -------- - ----- ------ ---- -- ------ -------- -------- --- -- ---- --- -------- ------ --- ----- ----- -------------- ------ -------- - ---- ---------- ------- ---- -- -- ---- ---- -- -------- ---- ------------ ------- --- -- -----
现在，除了上方的页面外，也可以引用之前定义的 Demo 组件在页面下放于，这也意味着我们可以在 Markdown 中添加各种各样的交互式或图形化组件和界面来进行进行展示和修饰。
2.5 一个 docz 应用的示例
检查好目录及文件结构的之后，我们就可以开始编写第一篇 docz 文章了。
在一个新的文件 doczrc.js 中填入以下内容：
-- -------------------- ---- -------
------ ----- ---- -------
------ - --- - ---- -----------------
------ ------- -
-------- -
-----
------------- ----------
----------- -----
---
--
----- -
---------------
-------- ---------
-
----- -------------
----- -
---------
---------
--------
--
--
--
------------ -
------- -
----- ----
------- --
-------- --
--
--
--
-pluginsArray: 这里会包含了所有的 docz 插件。menu: 这里定义了侧边栏的菜单及其嵌套菜单。themeConfig: 这里定义了我们页面主题所需的样式和 aptly message。
这个时候，我们可以编写我们的核心文档了，在 README.md 中编写它，docz 没有太多关于其用法的特殊限制，因此你完全可以像创作普通文档一样写作，不过请注意了本来格式的写法。另外，与 MDX 中一样，你也可以使用 JSX 代码段并引入组件文档等等。
- 这里是一些组件文档，包含了一些使用样例和参数的说明：
/src/components/**.
下面是一个例子，解释了如何编写组件文档：
-- -------------------- ---- ------- ------ ----- ---- ------- ------ - ----------- - ---- ------------------------------- - ----------- ---- -- - --------- ---- ---------- --- ---------- ------ ------------ ----------- - ----- --------
This is another paragraph where we can continue our text.
<MyComponent title="Another title"/>
2.6 构建和运行
在 package.json 文件中配置之后，现在我们就可以在开发环境中运行我们的 docz 应用。
输入以下代码：
yarn docz:dev
当我们执行完成后，我们应该就会看到如下所示的页面：
这样子完整地描述了使用 docz 的主要方法以及如何组织目录并运行文档。
3. 结尾
每个程序员都应该有一个好的文档内容输出习惯，在延续团队的衣钵的同时也强化自己的理解。分享就在这里，我们相信您已经可以应对 docz 的使用以 APP 集成，希望您在开发中能够更加方便的编写组件文档。
文献引用：
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/194333