docz：组件库⽂档soeasy!
docz ⽤于把 md ⽂件⾃动构建成⽂档⽹站，基于 mdx (markdowm + jsx)，可以在 markdown 中引⼊ react 组件，并且⽀持热更新，可以边写⽂档边调试。官⽅效果图长这样：
下⾯就记录⼀下怎样把 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
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
⽂档显⽰如下
问题
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<HTMLButtonElement>;
children?: React.ReactNode;
}
解决：
还是⾃⼰写吧，更加灵活
2. 没有渲染出任何内容
解决：
去 github 查看了下 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.
照此操作，果然奏效了，现在⽂档显⽰如下：
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 配置。htmlbutton属性
// gatsby-node.js
const path = require('path');
args.actions.setWebpackConfig({
module: {
rules: [
{
test: /\.(tsx|ts)$/,
/* ⚠ Note the '..' in the path because the docz gatsby project lives in the `.docz` directory */
include: [solve(__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 ⽂件中引⼊。
好了，最后看⼀下现在的⽂档：

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。