Docz 用 MDX 写 React UI 组件文档

Docz 用 MDX 写 React UI 组件文档

前言

为了提高开发效率，建立一套 UI 组件库是一种较为有效的方式之一：能够减小重复工做、提升可复用，因此如今愈来愈多团队开始建立本身的 UI 组件库。较早的 Twitter 的 Bootstrap 虽然只能称为 UI 库，但也大大提高了开发效率。后面 MVVM 大行其道 ，前端终于能够把 HTML、CSS、JS 放在一块儿开发包含 UI 、交互真正意义上的组件了，如今有基于 React 的 Material-UI、国内阿里金服基于 React 的 Ant Design、饿了么基于 Vue.js 的 Element、TalkingData 基于 Vue.js 的 iView 等。有了这些 UI 组件，让前端开发变得史无前例的方便，完成一个项目就像是拿一块块的积木(组件)堆成一个完整项目。

考虑到前期开发 UI 组件的工做量及后期维护成本，我认为在大厂开源 UI 组件库的基础上个性化色彩（通常都提供颜色定制）、增长团队的个性化需求组件、减小不须要的组件是个不错的主意。

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

左边是建立的 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