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 組件,讓前端開發變得史無前例的方便,完成一個項目就像是拿一塊塊的積木(組件)堆成一個完整項目。css

考慮到前期開發 UI 組件的工做量及後期維護成本,我認爲在大廠開源 UI 組件庫的基礎上個性化色彩(通常都提供顏色定製)、增長團隊的個性化需求組件、減小不須要的組件是個不錯的主意。html

有了團隊的 UI 組件庫就少不了使用文檔,畢竟文檔仍是比口口相傳要靠譜的多。這裏介紹一個能夠快速建立 React UI 組件庫使用、演示文檔的項目:DoczDocz 的特點是零配置、簡單、快速,它使用 Markdown 語法的擴展 MDX (在 Markdown 裏引入 React 組件並渲染出組件)來書寫文檔,對於熟悉 Markdown 的開發者是能夠直接上手的。下面貼一張官方的圖看看有多簡單:
Docz前端

左邊是建立的 MDX 文檔,右邊是 Docz 渲染出的組件及組件代碼。vue

是否是很方便?那下面簡單介紹一下使用步驟。react

使用

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 組件的演示、使用文檔。
git

更多詳情:http://www.docz.site/introduction/getting-startedgithub

配置

零配置方即是方便,但有時想界面個性化點仍是很費事的(官方提供 Themes 支持,但現僅有一套官方的默認主題),下面分享一個經過引入本地 CSS 的方式來改變默認主題的配置。npm

1. 建立配置文件 doczrc.js,增長 htmlContext 內容。

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

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
相關文章
相關標籤/搜索