docz: 组件库文档 so easy!

docz 用于把 md 文件自动构建成文档网站，基于 mdx (markdowm + jsx)，可以在 markdown 中引入 react 组件，并且支持热更新，可以边写文档边调试。
官方效果图长这样：

image.png

下面就记录一下怎样把 docz 加入碗中。

安装配置 docz

npm install docz -D

// doczrc.js
export default {
  files: './components/**/*.{md,markdown,mdx}', // 匹配要处理的文件
  dest: 'doc-site', // 打包出来的文件目录名
  title: 'xmh-ui', // 站点标题
  typescript: true // ts 项目需开启
}

使支持sass

npm install gatsby-plugin-sass -D

// gatsby-config.js
module.exports = {
  plugins: ['gatsby-plugin-sass']
}

添加 script

"doc": "docz dev",
"build:doc": "rimraf doc-site && docz build", // rimraf 需另外安装
"preview:doc": "docz serve"

使用

• 新建 mdx 文件 components/button/demo/index.mdx

• 编写文档

---
name: Button 按钮
route: /Button
menu: 组件
---

import { Playground, Props } from 'docz';
import { Button } from '../index';
import '../Button.scss';

# Button 按钮

## 参数

<Props of={Button} />

## 基本用法

<Playground>
    <Button type="primary" size="large">
        大号主按钮
    </Button>
</Playground>

• 执行 npm run doc

• 文档显示如下

  
  image.png

问题

1. 如上图文档显示，<Props> 没有支持 type 变量

// Button.tsx 

export type sizeType = 'large' | 'middle' | 'small';
export type brandType = 'primary' | 'success' | 'error' | 'info' | 'warning';

export interface ButtonProps {
    size?: sizeType;
    type?: brandType;
    loading?: boolean;
    disabled?: boolean;
    className?: string;
    onClick?: React.MouseEventHandler<HTMLButtonElement>;
    children?: React.ReactNode;
}

解决：

还是自己写吧，更加灵活

2. <Playground> 没有渲染出任何内容

解决：
去 github 查看了下 issue，发现很多人遇到了同样的问题，issue地址。
应该是某些依赖导致的问题，使用 npm 会出现问题，yarn 则不会。
github 上有人给出了解决的 hack:

• Removed node_modules, package-lock.json
• Add "@mdx-js/mdx": "^1.6.16" explicitly as a dev dependency.
• npm install
• npm run docz dev
• Playgrounds work now.

照此操作，果然奏效了，现在文档显示如下：

image.png

3. 如上图，按钮样式没有生效。

浏览器查看一下html

<div data-testid="live-preview" class="css-1yn7219-Playground">
    <button id="button" class="$prefix-button $prefix-size-large $prefix-type-primary button">
        大号主按钮
    </button>
</div>

如同预料，$prefix 没有替换。这项操作本地启动和打包时是在 webpack 中进行全局替换的，现在需要让 docz 也能处理一下。
解决：
项目根目录新建 gatsby-node.js，对 docz 所依赖的 gatby app 添加 webpack 配置。

// gatsby-node.js

const path = require('path');

exports.onCreateWebpackConfig = (args) => {
    args.actions.setWebpackConfig({
        module: {
            rules: [
                {
                    test: /\.(tsx|ts)$/,
                    /* ⚠ Note the '..' in the path because the docz gatsby project lives in the `.docz` directory */
                    include: [path.resolve(__dirname, '../components')], 
                    exclude: [/node_modules/],
                    use: [
                        'ts-loader',
                        {
                            loader: 'webpack-replace-loader',
                            options: {
                                arr: [{ search: '$prefix', replace: 'xmh', attr: 'g' }]
                            }
                        }
                    ]
                }
            ]
        }
    });
};

注意：

1. 配置里的 ../ 路径，因为这个 gatsby 项目运行在 .docz 文件夹里。
2. 这里为了直观直接把 $prefix 替换成了ui名 xmh，实际上 xmh 应该从一个 config.js 文件中引入。

好了，最后看一下现在的文档：

image.png