构建自己的React UI组件库(三)：文档编写

序言

该系列文章将跟随作者的开发进度持续更新。

预计内容如下：

构建自己的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 .mdx files 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 me</Button>
</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…