组件库文档建设指北
- 作者：Bougie
- 创建于：2019-06-22
- 更新于：2023-03-09
# 前言
前端现今基本是 React、Angular、Vue 三分天下了。伴随着三大框架的诞生，组件化开发成了前端开发的主流，连浏览器推行的 web components (opens new window) 都因这三大框架变得一直不温不火。组件库开发成为了热门，几年的积淀下来，诞生了诸如 Ant-Design、Material UI、Element UI等热门的开源组件库，而一个组件库好不好用、美不美观完全取决于文档做的怎么样。
大多数有一定规模的公司都有自己内部使用的组件库，然而只有 Ant Design 能做到其它组件库望尘莫及的地步，一是蚂蚁金服技术水平处于国内顶尖水平，二就是良好的开源氛围带来的收益，有良好开源氛围的公司必能引来众多的 Star 和巨量民间贡献者的 PR 。
然而精美文档的背后是巨大的工作量，绝大多数公司都做不到这点。
组件库文档最重要的有三点：美观、版本化、国际化。
# Vue 组件库
如果是 Vue 组件库，那么就不需要犹豫了，VuePress (opens new window)是你不二的选择，因为尤雨溪似乎已经亲自操刀把 Vue 的生态周边全部规划建设好了。
VuePress 是一个静态站点生成器，所有的 markdown 文件最后都会被编译成静态的 HTML。它具有良好的国际化功能 (opens new window)；版本化方面，对于小版本 API 的更替，使用 Badge (opens new window)即可，大的版本更替可以重开一个项目了。
你要做的，仅仅是开发一个漂亮的主题 (opens new window)而已。
# React 组件库
# Docusaurus
React 的话并没有像 Vue 那样那么顺利，官方并没有给出稳定好用的 markdown 嵌入 React 的方案。唯一还算比较官方的就是 facebook 的 Docusaurus，然而在 2.0 版本才有 mdx 支持计划，现在 2.0 版本还处于开发阶段，其中还大量借鉴了 VuePress 的设计思路 😌。
# Docz
还有一个工作量较少的选择就是 Docz (opens new window)，docz 已经集成了 mdx，可以直接在 mdx 文件中使用 React 组件，然而使用下来你会发现它完全就是一个巨坑 😡，看到这文字稀少、丑陋不堪的官方文档 (opens new window) 就有一种不好的预感。
# 版本化
# 大版本
利用子域名
如 ant.design (opens new window) 和 v2.ant.design (opens new window)
利用子路由
如 element.eleme.io (opens new window) 和 element.eleme.io/1.4 (opens new window)
# 小版本
小版本不可出现旧的 API 删除或修改，只能新增 API。
使用 Badge 标记
New Feature beta 0.10.1+