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

序言

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

预计内容以下：

---

构建本身的React UI组件库：

（一）：从v0.0.0到 v0.0.1

（二）：构建首页

（三）：文档编写 （本文）

（四）：擦干净细节

（五）：推广、宣传、迭代

<= to be continue =

---

在这里能够访问到个人组件库： BB-color

以及npm地址: BB-color

约定

1. 本系列文章尽量多的涉及到每一个步骤、每一个文件和每一个更新。
2. 本系列文章中，整个项目的开始基于官方提供的 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种方法来部署咱们的文档代码。

1. 购置一个服务器、域名，将咱们的代码推到服务器上，从域名中访问。
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…