構建本身的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…