序言
该系列文章将跟随作者的开发进度持续更新。
预计内容如下：
构建自己的React UI组件库：
（一）：从v0.0.0到 v0.0.1
（二）：构建首页
（三）：文档编写 （本文）
（四）：擦干净细节
（五）：推广、宣传、迭代
<= to be continue =
在这里可以访问到我的组件库： BB-color
以及npm地址: BB-color
约定
- 本系列文章尽可能多的涉及到每个步骤、每个文件和每个更新。
- 本系列文章中，整个项目的开始基于官方提供的
creat-react-app进行react构建，所有内容将使用最新的库版本进行开发。- create-react-app v2.1.1
- react v16.7.0
- webpack v4.19.1
- babel 7+
- node v10.15.0
- docz v0.13.7
必备知识
- 基本掌握 React
- 会使用 Git
- JavaScript、CSS等基础知识
正文开始
起点
UI组件库必备的内容，就是文档的编写，而这也是重中之重。我们将会使用docz来辅助我们进行文档开发。
注1：
docz可以快速创建 React UI 组件库使用、演示的文档，它使用Markdown语法的扩展 MDX (在 Markdown 里引入 React 组件并渲染出组件)来书写文档，目前只支持react。更多内容可以在 github 及 官方文档 上浏览
准备工作
执行以下命令安装需要的依赖
npm install --save-dev docz docz-theme-default docz-plugin-css @emotion/core
复制代码注2：
docz：docz核心部分，必须
docz-theme-default：docz默认主题，必须
docz-plugin-css： docz中使用CSS时的额外插件，如果不需要css则非必须
@emotion/core： 文档依赖，必须
安装完成后，修改我们的package.json
// package.json
{
...
"scripts": {
...
"docz:dev": "docz dev",
"docz:build": "docz build"
}
...
}
复制代码编写文档
我们在 src/components 里创建一个 home.mdx
补充知识点A：
不一定必须要在src里创建，官方文档中提到:
Note that you don't need to follow any strict file architecture. You can just create your
.mdxfiles anywhere in your project.docz能在任何地方识别到.mdx文件，所以你在哪里写文档都可以。你也可以另一起docz文件夹，单独存放你的文档文件，但是个人更推荐按照我们组件的目录结构进行书写，这样在后续修改的时候有利于我们直接找到需要的内容。
// src/components/home.mdx
---
name: 首页
route: /
---
# Hello world
Hello, I'm a mdx file!
复制代码然后在 src/components/button 里创建 button.mdx
// src/components/button/button.mdx
---
name: Button
route: /button
---
import { Playground, PropsTable } from 'docz'
import Button from './index.js'
# Button
<PropsTable of={Button} />
## Basic usage
<Playground>
<Button>Click meButton>
Playground>
复制代码文档部分的编写到这里就结束了，接下来是配置的编写
在根目录下创建 doczrc.js
// doczrc.js
import { css } from 'docz-plugin-css'
export default {
title: 'BB Color',
description: 'A Design UI library for React',
plugins: [
css({
preprocessor: 'postcss'
})
]
}
复制代码完成以上操作后，整个项目目录会变成这样
随后，就像运行 npm start 一样，我们通过 gitbash 执行 npm run docz:dev
如果没有问题，你会看见下面的页面
恭喜你，你已经成功构建出你自己的文档。 你可以点击左侧的 “首页”、“Button” 查看具体的内容。
目前我们只做了非常非常基础的部分，本篇文章也只会讲解最基本的内容搭建，具体每一个细节，每一篇文档就交给你和你的创造力共同完成。
*打包导出(非必须)
打包导出就比较简单了，直接 npm run docz:build ，你就能在 .docz/dist 里找到你的静态文件。 如果你想打包到其他文件夹，可以在 doczrc.js 进行配置
你可以在这里找到相关配置：
www.docz.site/introductio…
这一步我保持原样，不做处理。
执行打包后，会是这样
./.docz/dist 存放的就是我们打包后的文件
提交代码
在提交代码之前，修改一下 .gitignore
// .gitignore
...
/.docz
...
复制代码随后就是正常的提交了
git add .
git commit -m '文档创建'
git push -u origin master
复制代码等等！ 还没完！
在代码提交后，还不能进入到文档页，我们还需要部署我们的文档代码
部署代码
我们打包出来的文件是静态文件，我们需要单独部署。
也许你想到，在docs里面创建一个doc文件，将dist里的文件放在doc里面，像首页一样，通过github pages直接进入。
但是很不幸的是，这种方法不可行。
这里有一个问题。 docz打包出来的资源文件，引用是基于路由根部的绝对路径。
举例来说，我在
docs/路径下启动了一个本地服务，地址为http://127.0.0.1/，我们能正常访问到docs/index.html。当我们访问文档页时，地址改为http://127.0.0.1/doc，我们也能访问到docs/doc/index.html但是所有的资源都加载不上，因为引用的资源会在启动服务器的根目录(docs)寻找，而不是在相对路径./docs/doc里面寻找。我们通过github pages 生成的网站，地址是这样：
https://bb-color.github.io/BB-color/在https://bb-color.github.io里是找不到我们需要的静态文件。
这里有2种方法来部署我们的文档代码。
- 购置一个服务器、域名，将我们的代码推到服务器上，从域名中访问。
- 使用 Netlify 帮我们部署。
使用 Netlify 部署
Netlify是一个非常棒的简单工具，允许你通过在几秒钟内从分支机构的每次推送运行部署，以自动方式部署你的应用程序，并且它还免费
进入 netlify ，使用github注册登录
登录成功后，自动跳转到个人首页，然后跟着下图红色箭头的指示一起做。
然后只需要选择我们的组件库文件即可
接下来有3个需要设置的地方，
-
第一个是选择分支，我们就选Master即可
-
第二个是输入构建命令，输入我们在package.json里设置的文档构建命令。
-
第三个是输入 当执行了文档构建命令后，打包出来的文件路径，因为路径我没做修改，输入默认的
.docz/dist即可，
然后点击 deploy site 进行部署
在下图的第一步期间它会自动部署，只需要等待第一步完成即可。
部署完成后，你能在红色箭头访问到部署后的网站。如果你对域名不满意，你可以在黄色箭头处配置自己的域名。
我们只需设置这一次，以后每次我们提交代码的时候，Netlify会自动帮我们部署最新的代码。
再次提交
提交之前，修改我们的主页，让我们的主页能跳转到我们的文档页。
git tag -a 'v0.0.3' -m '文档构建'
git push origin v0.0.3
git add .
git commit -m '文档引用'
git push -u origin master
复制代码恭喜你，一个具有首页与文档说明的UI组件库就搭好了！！
尾声
本以为这个系列最重要的3篇会写很久，没想到肝得这么快，毕竟还有其他压力在迫使我尽快完成这部分内容，23333
之后第四章与第五章属于附加篇，没有前三章那么重要，之后也不会写得这么快了。2333
如果有任何不当或缺失的地方，希望能在评论区指出，理性交流。
如需转载请注明作者与原文地址
作者：ParaSLee
原文：juejin.im/post/5c304b…