對於前端團隊來說，公共組件庫是必須的，緊接着就是完善組件庫的文檔
社區里關於快速生成文檔的工具有很多，如 StoryBook、Docz、Gatsby
在調研了幾種文檔工具之后，最終我選擇了 umi 家族的另一個成員：dumi
因為它集成了 docz，以及打包工具 father-build，同時支持創建自己的 Markdown 組件
當然最重要的是，我的項目是基於 umi 構建的
一、啟動
首先創建一個項目目錄
mkdir myapp && cd myapp
然后初始化組件庫，這里有兩種選擇：
1. 文檔模式：
yarn create @umijs/dumi-lib
2. 站點模式
yarn create @umijs/dumi-lib --site
創建項目后，首先執行 yarn 安裝依賴，然后執行 yarn start 即可查看文檔項目
// 接下來將介紹文檔模式，主要針對 dumi 官網中沒有詳細描述的地方進行補充
二、組件庫打包
組件庫的依賴項 dependencies 應該只包含自身用到的模塊，如 classnames
其他的依賴應該盡量用 peerDependencies 和 devDependencies 來管理
組件庫的入口是文件是 index.ts，需要打包的組件都應該從這里導出
dumi 使用 father-build 來打包，其配置文件是 .fatherrc.ts，詳細配置可以參考 father 的文檔
假如 src 目錄下有一個 Button 組件：
// src/Button/index.tsx
import React from 'react'; import './index.less'; const Button: React.FC<any> = () => { // ...
} export default Button;
只需要在 src/index.ts 中導出該組件：
// src/index.ts
export { default as Button } from './Button';
然后簡單的配置下 .fatherrc.ts
// .fatherrc.ts
export default { esm: 'rollup', };
就能使用 yarn build 打包組件庫了
打包后的文件在 dist 目錄下，另外在 package.json 中已經默認配置好了路徑
接下來只需要 npm publish 發布到自己配置的 npm 倉庫就行
如果在打包的過程中遇到問題，可以到 father 的 GitHub 倉庫中找找 issues
三、文檔站點
組件打包已經搞定，接下來就是完善組件的文檔
dumi 會基於 src 目錄下的 index.md 文件（或者 README.md）生成頁面及默認路由
比如剛才的 Button 組件，目錄下有一個 index.md（src/Button/index.md）
在瀏覽器中就能通過 http://localhost:8000/button 訪問到該頁面
1. 組件 Demo
dumi 可以直接在 Markdown 文件中寫 jsx，然后會在頁面中渲染成組件
```jsx import React from 'react'; export default () => <h1>Hello dumi!</h1>; ```
如果不希望代碼塊被渲染，可以使用 pure 修飾符
```jsx | pure import React from 'react'; export default () => <h1>Hello dumi!</h1>; ```
更多的用法可以參考官網《寫組件 demo》
2. 自定義導航與分組
dumi 導航是基於文件目錄來的，首頁渲染的是 docs/index.md
其他的導航路徑默認是根據 src 下的文件結構生成的
比如這樣的文件結構：
會生成這樣的導航：
如果希望自定義導航（分組、排序、改標題），可以在 Markdown 文件頂部編寫 FrontMatter
--- title: 自定義頁面名稱 nav: path: /自定義導航路由 title: 自定義導航名稱 order: 控制導航順序，數字越小越靠前，默認以路徑長度和字典序排序 group: path: /自定義分組路由，注意，分組路由 = 導航路由 + 自己 title: 自定義分組名稱 order: 控制分組順序，數字越小越靠前，默認以路徑長度和字典序排序 ---
<!-- 其他 Markdown 內容 -->
比如這樣的結構
其中 Button 和 Select 組件可以歸類為“表單組件”，Container 可以歸類為“布局組件”
那就可以在 Container 組件的 index.md 文件頂部添加“布局組件”的分組信息：
--- order: 1 group: path: /layout title: 布局組件 order: 1
---
然后在 Button、Select 組件的 index.md 文件頂部添加“表單組件”的分組信息：
--- order: 2 group: path: /form title: 表單組件 order: 2
---
順便給首頁文件 docs/index.md 添加一個 order
--- order: 0
---
這樣就能實現自定義導航了
3. 引入外部組件
由於文檔站點的頁面是 MarkDown 文件，雖然在 dumi 讓我們可以在 MarkDown 中寫 jsx 組件，
但如果某個組件的 Demo 比較復雜，甚至包含很多外部文件，
這時候可以在其他地方寫好 demo，然后在 MarkDown 文件中，通過 <code> 標簽引入
<code src="/path/to/complex-demo.tsx"></code>
--------------------------------------
最后需要注意一下，對於文檔站點的打包需要使用 yarn docs:build 命令
四、Demo 理念
開發文檔站點的時候，需要牢記一條宗旨：開發者應該像用戶一樣寫 Demo
這是 dumi 官方文檔中提到的，我深以為然
建議每一個寫組件文檔的小伙伴都了解一下，傳送門：
https://d.umijs.org/zh-CN/guide/demo-principle