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 按钮

## 参数



## 基本用法


    

  • 执行 npm run doc

  • 文档显示如下


    image.png

问题

  1. 如上图文档显示, 没有支持 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;
    children?: React.ReactNode;
}

解决:

还是自己写吧,更加灵活

  1. 没有渲染出任何内容

解决:
去 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
  1. 如上图,按钮样式没有生效。

浏览器查看一下html

如同预料,$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

你可能感兴趣的:(docz: 组件库文档 so easy!)