组件库文档建设指北

作者: Bougie 创建于: 2019-06-22 | Vue React

ZpLnVs.png

# 前言

前端现今基本是 ReactAngularVue 三分天下了。伴随着三大框架的诞生,组件化开发成了前端开发的主流,连浏览器推行的 web components 都因这三大框架变得一直不温不火。组件库开发成为了热门,几年的积淀下来,诞生了诸如 Ant-DesignMaterial UIElement UI等热门的开源组件库,而一个组件库好不好用、美不美观完全取决于文档做的怎么样。

大多数有一定规模的公司都有自己内部使用的组件库,然而只有 Ant Design 能做到其它组件库望尘莫及的地步,一是蚂蚁金服技术水平处于国内顶尖水平,二就是良好的开源氛围带来的收益,有良好开源氛围的公司必能引来众多的 Star 和巨量民间贡献者的 PR 。

然而精美文档的背后是巨大的工作量,绝大多数公司都做不到这点。

组件库文档最重要的有三点:美观、版本化、国际化。

# Vue 组件库

如果是 Vue 组件库,那么就不需要犹豫了,VuePress是你不二的选择,因为尤雨溪似乎已经亲自操刀把 Vue 的生态周边全部规划建设好了。

VuePress 是一个静态站点生成器,所有的 markdown 文件最后都会被编译成静态的 HTML。它具有良好的国际化功能;版本化方面,对于小版本 API 的更替,使用 Badge即可,大的版本更替可以重开一个项目了。

你要做的,仅仅是开发一个漂亮的主题而已。

# React 组件库

# Docusaurus

React 的话并没有像 Vue 那样那么顺利,官方并没有给出稳定好用的 markdown 嵌入 React 的方案。唯一还算比较官方的就是 facebook 的 Docusaurus,然而在 2.0 版本才有 mdx 支持计划,现在 2.0 版本还处于开发阶段,其中还大量借鉴了 VuePress 的设计思路 😌。

# Docz

还有一个工作量较少的选择就是 Docz,docz 已经集成了 mdx,可以直接在 mdx 文件中使用 React 组件,然而使用下来你会发现它完全就是一个巨坑 😡,看到这文字稀少、丑陋不堪的官方文档 就有一种不好的预感。

# 版本化

# 大版本

利用子域名
ant.designv2.ant.design

利用子路由
element.eleme.ioelement.eleme.io/1.4

# 小版本

小版本不可出现旧的 API 删除或修改,只能新增 API。

使用 Badge 标记

New Feature beta 0.10.1+

上次更新: 2019-11-1 3:39:35 PM