阅读 1971

构建自己的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…

关注下面的标签,发现更多相似文章
评论