使用dumi生成react組件庫文檔並發佈到github pages

• 2021 年 12 月 5 日
• 筆記
• javascript, React

周末兩天玩了下號稱西湖區東半球最牛逼的react文檔站點生成工具dumi，順帶結合github pages生成了react-uni-comps文檔站， 一套弄下來，感覺真香，現在還只是淺嘗，高級的特性還沒玩完，文檔還需繼續打磨完整，不知道是不是東半球最牛逼，西湖全區應該無與倫比了 😃，下面是當前文檔站移動端和pc端預覽截圖（整套弄下來花了半天時間!）

桌面端效果(手機界面模擬/桌面端效果/自動根據ts生成的API表格文檔)

手機效果(支持light/dark主題)

文檔站點製作步驟如下：

1. 安裝 dumi 和移動端主題 dumi-theme-mobile

 yarn add -D dumi dumi-theme-mobile

2. 添加配置文件.umirc.ts,下面是我的配置

import { defineConfig } from 'dumi';

const repo = 'react-uni-comps';

const logo =
  'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9Ii0xMS41IC0xMC4yMzE3NCAyMyAyMC40NjM0OCI+CiAgPHRpdGxlPlJlYWN0IExvZ288L3RpdGxlPgogIDxjaXJjbGUgY3g9IjAiIGN5PSIwIiByPSIyLjA1IiBmaWxsPSIjNjFkYWZiIi8+CiAgPGcgc3Ryb2tlPSIjNjFkYWZiIiBzdHJva2Utd2lkdGg9IjEiIGZpbGw9Im5vbmUiPgogICAgPGVsbGlwc2Ugcng9IjExIiByeT0iNC4yIi8+CiAgICA8ZWxsaXBzZSByeD0iMTEiIHJ5PSI0LjIiIHRyYW5zZm9ybT0icm90YXRlKDYwKSIvPgogICAgPGVsbGlwc2Ugcng9IjExIiByeT0iNC4yIiB0cmFuc2Zvcm09InJvdGF0ZSgxMjApIi8+CiAgPC9nPgo8L3N2Zz4K';

export default defineConfig({
  title: repo,
  favicon: logo,
  logo: logo,
  outputPath: 'docs',
  mode: 'doc',
  resolve: {
    // 配置 dumi 嗅探的文檔目錄
    includes: ['mdx'],
  },
  hash: true,
  // 使用 webpack 5進行構建。
  webpack5: {},
  // 通過 [webpack-chain](//github.com/mozilla-neutrino/webpack-chain) 的 API 修改 webpack 配置。
  chainWebpack(memo, { env, webpack, createCSSRule }) {
    memo.cache = {
      type: 'filesystem',
      name: 'dumi',
      buildDependencies: {
        config: [__filename],
      },
      store: 'pack',
    };
    memo.plugins.delete('friendly-error');
    memo.plugins.delete('copy');
  },
  // github page
  base: `/${repo}/`,
  publicPath: `/${repo}/`,
  // 自定義樣式
  styles: [
    `
    #root .__dumi-default-menu-header p {
      display:none;
    }
    #root .__dumi-default-menu-header h1 {
      font-size: 24px;
      margin: 16px auto;
    }
    `,
  ],
  themeConfig: {
    carrier: '中國移動',
    hd: {
      // 禁用高清方案
      rules: [],
      // 更多 rule 配置訪問 //github.com/umijs/dumi/blob/master/packages/theme-mobile/src/typings/config.d.ts#L7
    },
  },
});

3. 編寫組件文檔，以/mdx/Button.md舉例子, 我把文檔放在了mdx目錄,因為github pages需要使用docs目錄

---
title: 按鈕
order: 0
mobile: true
group:
  title: 基礎組件
  order: 0
  path: base
---

<code src="../demo/Button.jsx"></code>
<API src="../src/Button.tsx"></API>

4. 因為組件比較多，我這裡markdown文檔通過ejs動態生成，當組件api/demo更新時，可以自動更新文檔,無需手工維護

 // 數據配置
 module.exports = [
  {
    title: '基礎組件',
    path: 'base',
    comps: [
      {
        name: 'Button',
        title: '按鈕',
      },
      {
        name: 'Icon',
        title: '圖標',
      },
    ],
    ........
  },
];
// 文檔生成

/* eslint-disable @typescript-eslint/no-var-requires */
const ejs = require('ejs');
const data = require('./doc-data');
const path = require('path');
const fs = require('fs');

const tpl = `---
title: <%= title %>
order: <%= order %>
mobile: <%= mobile %>
group:
  title: <%= groupTitle %>
  order: <%= groupOrder %>
  path: <%= groupPath %>
---

<code src="../demo/<%= name %>.jsx"></code>
<API src="../src/<%= name %>.tsx"></API>
`;

data.map((group, idx) => {
  group.comps.map((item, subIdx) => {
    item.order = subIdx;
    item.groupOrder = idx;
    item.groupPath = group.path;
    item.groupTitle = group.title;
    item.mobile = typeof item.mobile === 'boolean' ? item.mobile : true;

    const fileName = path.resolve(__dirname, `./mdx/${item.name}.md`);

    if (fs.existsSync(fileName)) {
      fs.unlinkSync(fileName);
    }

    fs.writeFileSync(path.resolve(__dirname, `./mdx/${item.name}.md`), ejs.render(tpl, item));
  });
});

5. 開發構建

開發命令: dumi dev 
開發命令: dumi build 

6. 配置github pages

點擊項目settings->左邊的Pages一欄， 設置Source， 我這裡選擇master分支, /docs目錄託管構建的文檔站，點擊save保存， 然後打開上面他告之的github pages鏈接即可預覽