Docz 用 MDX 写 React UI 组件文档

Docz 用 MDX 写 React UI 组件文档

前言

为了提升开发效率,创建一套 UI 组件库是一种较为有效的方式之一:可以减少重复工作、提高可复用,所以现在越来越多团队开始创建自己的 UI 组件库。较早的 Twitter 的 Bootstrap 虽然只能称为 UI 库,但也大大提升了开发效率。后面 MVVM 大行其道 ,前端终于可以把 HTML、CSS、JS 放在一起开发包含 UI 、交互真正意义上的组件了,现在有基于 ReactMaterial-UI、国内阿里金服基于 ReactAnt Design、饿了么基于 Vue.jsElement、TalkingData 基于 Vue.jsiView 等。有了这些 UI 组件,让前端开发变得前所未有的方便,完成一个项目就像是拿一块块的积木(组件)堆成一个完整项目。

考虑到前期开发 UI 组件的工作量及后期维护成本,我认为在大厂开源 UI 组件库的基础上个性化色彩(一般都提供颜色定制)、增加团队的个性化需求组件、减少不需要的组件是个不错的主意。

有了团队的 UI 组件库就少不了使用文档,毕竟文档还是比口口相传要靠谱的多。这里介绍一个可以快速创建 React UI 组件库使用、演示文档的项目:DoczDocz 的特色是零配置、简单、快速,它使用 Markdown 语法的扩展 MDX (在 Markdown 里引入 React 组件并渲染出组件)来书写文档,对于熟悉 Markdown 的开发者是可以直接上手的。下面贴一张官方的图看看有多简单:
Docz

左边是创建的 MDX 文档,右边是 Docz 渲染出的组件及组件代码。

是不是很方便?那下面简单介绍一下使用步骤。

使用

1. 在你的项目里安装 Docz:
yarn add docz --dev 或者 npm install docz --save-dev
2. 创建 .mdx 文件并输入:
---
name: Button
---

import { Playground, PropsTable } from 'docz'
import Button from './'

# Button

<PropsTable of={Button} />

## Basic usage

<Playground>
 <Button>Click me</Button>
 <Button kind="secondary">Click me</Button>
</Playground>
3. 运行:
yarn docz dev

然后就完成了一个简单的 Button 组件的演示、使用文档。

更多详情:http://www.docz.site/introduction/getting-started

配置

零配置方便是方便,但有时想界面个性化点还是很费事的(官方提供 Themes 支持,但现仅有一套官方的默认主题),下面分享一个通过引入本地 CSS 的方式来改变默认主题的配置。

1. 创建配置文件 doczrc.js,增加 htmlContext 内容。

更多配置:https://www.docz.site/documentation/project-configuration

export default {
  htmlContext: {
    head: {
      links: [
        { rel: 'stylesheet', href: '/base.css' }
      ]
    }
  }
}
2. .docz 目录下创建 public 文件夹并创建 base.css,在 base.css 里写自己的样式覆盖默认的即可。

最后

  • Docz 简单好用,但现在只支持 React。
  • Storybook 是一个更强大的集组件开发、查看、测试的文档工具,支持:
    • React
    • React Native
    • Vue
    • Angular
    • Polymer
    • Mithril
    • Marko
    • HTML
    • Svelte
    • Riot
  • Docsify搭配 Vuep 写 Playground
转载请注明出处: https://blog.givebest.cn/other/2018/09/15/react-ui-component-docz-mdx.html
posted @ 2018-09-15 22:34 givebest 阅读(...) 评论(...) 编辑 收藏