前端组件库文档解决方案


本篇主要分享什么内容：

- 常用的文档/静态站点生成工具有哪些
- 每个工具有什么特点
- 工具适应场景

### 前置概念

- [MarkDown](https://markdown.com.cn/)
- [MDX](https://mdxjs.com/) MarkDown + JSX
- [YMAL Front Matter](https://hexo.io/zh-cn/docs/front-matter.html)

### 组件库文档工具选型

AndD组件库文档是怎么制做的，使用了什么工具。

以AntD Button组件为例，我们看一下antd组件库的文档页面结构构成和文档生成：

[Button文档](https://ant.design/components/button-cn/)

[Button文档仓库源文件](https://github.com/ant-design/ant-design/blob/master/components/button/index.zh-CN.md)

[网站文档仓库源文件](https://github.com/ant-design/ant-design/blob/master/docs/resources.zh-CN.md)

[按钮类型](https://raw.githubusercontent.com/ant-design/ant-design/master/components/button/demo/basic.md)

[bisheng](https://github.com/benjycui/bisheng)

AntD使用了bisheng来生成组件库文档，把MarkDown进行拼接和渲染成最终的文档展示页面。


### 静态站生成工具方案

1. [vuePress](https://vuepress.vuejs.org/zh/guide/directory-structure.html#%E9%BB%98%E8%AE%A4%E7%9A%84%E9%A1%B5%E9%9D%A2%E8%B7%AF%E7%94%B1)


2. [gitbook](https://docs.gitbook.com/)


3. [MDX](https://www.mdxjs.cn/)

MarkDown + JSX

支持导入React组件

支持remark 生态系统中的任何插件

Playground 实时修改，实时预览

**基础**

支持MarkDown语法

完全支持JSX 以`<`字符开头的行都视为JSX代码块

支持import 和 exports

*import* 组件 json数据 md或mdx文档

**MDXProvider**

提供MarkDown渲染HTML使用组件的映射 [组件列表](https://www.mdxjs.cn/table-of-components)

 

4. [Gatsby](https://www.gatsbyjs.com/)

[Demo](https://introworkshopexamplesitev3.gatsbyjs.io/blog)

1. 初始化

```bash
npm init gatsby
```

```bash
npm install -g gatsby-cli
gatsby new
```

2. 运行

```bash
npm run develop
```

3. 特点：生态好，功能丰富，有各种各样的[插件](https://www.gatsbyjs.com/plugins/)，支持MDX。

Gatsby 有一个强大的功能，称为**数据层**，使用 Gatsby 的数据层，您可以组合来自多个来源的数据，这让您可以为每种类型的数据选择最佳平台。

![显示数据如何流入和流出 GraphQL 数据层的图表。 源插件将数据从特定数据源中提取到您站点的数据层中。 GraphQL 查询将数据从数据层中提取到您的 React 组件中。](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/450fd819c730409d9ac8ddf4c8e9341d~tplv-k3u1fbpfcp-zoom-1.image)

http://localhost:8000/___graphql中可以看到GraphQL数据

4. 数据来源
Gatsby-source-*

数据拉入：页面数据拉入 使用页面查询，页面中导出 query，通过graphql查询即可

​ 组件中拉入数据 可以使用useStaticQuery钩子拉入，

5. 动态创建页面

Gatsby的 [文件系统路由 API](https://www.gatsbyjs.com/docs/reference/routing/file-system-route-api/)定义用于命名`src/pages`目录中文件的特殊语法，它允许您根据数据层中的节点**集合**为站点动态创建新页面。

 

5. [JSDoc](https://github.com/jsdoc/jsdoc)

根据javascript文件中注释信息，生成JavaScript应用程序或库、模块的API文档 的工具

**安装**

```bash
npm install -D jsdoc
```

**使用**

```bash
jsdoc xxx.js
```

默认会输出文档到`out`文件夹，可以通过`--destination`指定输出路径

[jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown)

 

6. [TSDoc](https://www.npmjs.com/package/@microsoft/tsdoc)

https://tsdoc.org/play

 

7. [React Styleguidist](https://react-styleguidist.js.org/)

 

8. [StoryBook](https://storybook.js.org/docs/react/get-started/introduction)

​ 一个强大的集组件开发，查看，测试的文档工具，支持多种框架。使用”组件驱动开发“理念。

- 支持多种框架 React Vue Angular Ember Preact Svelte等

[Tutorials](https://storybook.js.org/tutorials/intro-to-storybook/react/en/get-started/)

[CDD](https://www.componentdriven.org/)

 

9. [docsify](https://docsify.js.org/#/)

**特点：**

- 简单轻便
- 没有静态构建的 html 文件
- 多个主题

**安装**

```bash
npm i docsify-cli -g
```

**初始化**

```bash
docsify init ./docs
```

**预览**

```
docsify serve docs
```

**目录结构**

`index.html` 文件入口

`README.md` 主页

`.nojekyll` 防止GitHub Pages忽略以下划线开头的文件

**侧边栏**

创建 _sidebar.md（支持目录层级嵌套）。

_sidebar.md中页面会自动生成标题和子标题

**自定义导航栏**

- html标签
- _navbar.md（同样支持目录层级嵌套，展示形式为弹窗）

**封面**

_coverpage.md `#/` 首页全屏展示

可以指定背景图和背景色

可以指定只展示封面

**配置**

window.$docsify = {

​ el:'#app', // 根元素

​ repo:'docsifyjs/docsify/', //Git仓库地址

​ maxLevel: 6, // 目录最大层级

​ loadNavbar: false, // 加载_navbar.md作为导航栏(或者直接指定md路径)

​ loadSidebar: false, // 加载_sidebar.md作为侧边栏

​ hideSidebar: true, // 隐藏侧边栏

​ subMaxLevel: 0, // 在自定义侧边栏中添加目录（最大层级）

​ auto2top: true, // 页面路径改变时滚动到屏幕顶部

​ homepage: 'README.md', // `#/` 主页

​ basePath: '/path/', // 基本路径, 可以将其设置为其他目录或其他域名

​ relativePath: false, // 如果为 true，则链接是相对于当前上下文的。

​ coverpage: false, // 封面 默认加载_coverpage.md，也可以指定md路径

​ logo,

​ name,

​ nameLink,

​ markdown, // 自定义渲染MarkDown为HTML [文档](https://docsify.js.org/#/markdown)

​ themeColor,

​ executeScript: true,

​ mergeNavbar: true, // 小屏幕上的导航栏将与侧边栏合并

​ externalLinkTarget: '_self', // default: '_blank' 打开默认连接方式

​ routerMode: 'history', // default: 'hash' 路由模式

​ onlyCover: false, // `#/`只展示封面

​ requestHeaders: { 'x-token': 'xxx', }, // 设置请求资源头

​ notFoundPage: true, // 加载_404.md 或指定相应的md

​ vueComponents, // 注册vue组件, 可在md中直接使用

​ vueGlobalOptions,

​ vueMounts

}

**[主题](https://docsify.js.org/#/themes)** 官方和社区制作的主题

**[插件](https://docsify.js.org/#/plugins)** 全文检索，谷歌分析，表情符号，第三方脚本支持，图片缩放，在github上编辑，jsfiddler Demo预览，复制到剪切板，Gitalk, 分页和标签[等](https://docsify.js.org/#/awesome?id=plugins)

[PWA](https://docsify.js.org/#/pwa)

[SSR](https://docsify.js.org/#/ssr)

嵌入文件：支持视频， 音频，iframe或代码块，甚至MarkDown

 

10. [Docz](https://www.docz.site/)

- 基于MDX进行了封装
- 完全使用Gatsby构建，可以使用Gatsby的插件和工具生态
- 零配置
- TypeScript支持

**安装**

```bash
npm install docz # react react-dom
```

**运行**

```json
"scripts": {
"docz:dev": "docz dev",
"docz:build": "docz build",
"docz:serve": "docz build && docz serve"
}
```

**开发**

创建.mdx文件即可(指定name和route)。

**构建**

```bash
npm run build # 生成静态资源在.docz/dist目录中
npm run build -- --dest docs-site-directory # 通过--dest 指定文档生成目录
```

也可以在配置中指定打包输出目录

```js
// doczrc.js
export default {
dest: '/some-folder'
}
```

**部署**

构建之后可以使用任何静态站点托管服务进行部署。

**MDX支持**

可以直接引入.jsx/.tsx组件，样式；

**内置组件**

- Playground

Playground支持编辑实时渲染，支持函数组件和State

- Props

组件内的prop-types定义和typeScript的Interface会通过<Props>转换成表格展示

**文档设置**

使用YMAL自定义文档设置(也可以自定义属性，用于自定义theme)

```markdown
---
name: My Document
route: /custom-route
menu: Documents
hidden: false
---
```

**CSS预处理器**

需要Gatsby提供的能力，安装插件

**TypeScript支持**

```js
// doczrc.js
export default {
typescript: true
}
```

如果需要精确控制组件后缀，可以使用`filterComponents` and `docgenConfig`进行过滤

**支持自定义主题**

**项目配置**

*基本配置*

`base` 页面访问的basePath

`src` 指定组件存放目录

`files` 指定docz解析文件查找路径规则 默认会查找所有扩展名为.mdx的文件

`ignore` 需要忽略解析的文件

`dest` 指定docz build的目录

`title` Header展示title，默认会去package.json中name字段

`description` HTML中meta字段

`typescript` typescript支持 默认false .mdx文件中需要引入TypeScript组件则需要设置

`propsParser` props格式化 供<Props />渲染使用，禁用可以提升性能。

`config` 指定docz配置文件 默认顺序 ` docz.json | .doczrc | doczrc.json |doczrc.js | docz.config.js | docz.config.json`

`public` 指定公共目录，绝对资源路径会从这个目录下取数据

`editBranch` 点击 Github 按钮时用于编辑文档的分支

`host` devServer地址 默认 '127.0.0.1'

`port` devServer 端口

*构建流程*

`menu` 可指定菜单中文档的顺序

`plugins` 指定要使用的插件数组

**组件和HooksAPI**

`ComponentsProvider` 将组件传递给 MDX，它们将在您将 Markdown 转换为 html 时使用

`Playground` 渲染组件并在其中显示代码的可编辑版本

``Props`` 获取组件并根据组件中属性定义生成属性表的组件

`useComponents` 配合ComponentsProvider使用

`useDocs` 获取所有已解析文档的列表, 当要创建菜单或列表之类的内容时会很有用。

`useMenus` 返回 Docz 构建的菜单

`useConfig ` 获取项目配置中项目配置对象

**支持自定义插件和MDX插件**

> 使用注意：每次涉及到路由的变化都需要重启生效，遇到缓存问题可以删除.docz文件夹后重启

```js
// 一个简单的docz配置 doczrc.js
export default {
files: './docs/mdx/*.{md,markdown,mdx}',
dest: './docs/site',
title: 'Flex-Ctrip-Offline',
typescript: true
}
```

 

11. [Dumi](https://d.umijs.org/zh-CN/guide)

- 开箱即用
- 为组件开发而生，支持Markdown扩展，可以渲染组件
- 主题系统，支持自定义渲染样式
- API自动生成，基于TypeScript类型定义自动生成组件API

**组件开发脚手架**

```bash
npx @umijs/create-dumi-lib # 初始化一个文档模式的组件库开发脚手架
npx @umijs/create-dumi-lib --site # 初始化一个站点模式的组件库开发脚手架 (比文档模式多一个主页，主页使用docs/index.md)
# 也可手动切换文档模式 => 站点模式: 修改.umirc.ts,添加mode:'site'
```

**静态站点脚手架**

```bash
npx @umijs/create-dumi-app
```

**运行**

```bash
npm install
npm start
```

**构建及部署**

```bash
npm run build
```

**目录结构**

```bash
├── README.md
├── docs # 组件库文档目录
│   ├── index.md # 组件库文档首页(不存在会使用README.md)
│   └── otherDir # 组件文档其他路由
│   ├── index.md
│   ├── sample.md
│   └── help.md
├── src # 组件库源码目录(单纯文档站点可忽略)
│   ├── Foo
│   └── index.ts
├── .umirc.ts # dumi配置文件
└── .fatherrc.ts # father-build的配置文件用于组件库打包
```

**代码块**

jsx和tsx的代码块会被dumi解析为React组件，并进行渲染。

**dumi引入组件原则：**

​ 像用户一样使用组件：直接引入组件库进行文档demo演示。不仅可以用来调试组件、编写文档，还能用来被用户直接拷贝到项目中使用。dumi会为我们自动创建组件库NPM包->组件库源代码的映射。

**外部demo**

可以引入外部文件作为demo渲染，并可支持查看demo源代码

```html
<code src="/path/to/complex-demo.tsx"></code>
```

**直接嵌入渲染**

~~~markdown
```jsx
/**
* inline: true
*/
import React from 'react';
export default () => '我会被直接嵌入';
```
~~~

**embed Markdow嵌套**

```html
<!-- 引入全量的 Markdown 文件内容 -->
<embed src="/path/to/some.md"></embed>
<!-- 根据行号引入指定行的 Markdown 文件内容 -->
<embed src="/path/to/some.md#L1"></embed>
<!-- 根据行号引入部分 Markdown 文件内容 -->
<embed src="/path/to/some.md#L1-L10"></embed>
<!-- 根据正则引入部分 Markdown 文件内容 -->
<embed src="/path/to/some.md#RE-/^[^\r\n]+/"></embed>
```

**[组件API自动生成](https://d.umijs.org/zh-CN/guide/advanced#%E7%BB%84%E4%BB%B6%E6%BA%90%E7%A0%81%E4%B8%AD%E7%9A%84%E7%B1%BB%E5%9E%8B%E5%92%8C%E6%B3%A8%E8%A7%A3)**

JS Doc注释 + TypeScript类型定义的方式实现组件API自动生成

[如何在非-umi-项目中使用-dumi](https://d.umijs.org/zh-CN/guide/faq#%E5%A6%82%E4%BD%95%E5%9C%A8-cra-%E7%AD%89%E9%9D%9E-umi-%E9%A1%B9%E7%9B%AE%E4%B8%AD%E4%BD%BF%E7%94%A8-dumi%EF%BC%9F)

[DEMO理念](https://d.umijs.org/zh-CN/guide/demo-principle)

> 目前我们选择的是使用Docz来做为业务组件库的文档生成工具，下一篇会讲一下我们为什么选择Docz,它有什么优点。欢迎持续关注，微信公众号”混沌前端“

posted @ 2022-04-15 12:09  一颗小行星-  阅读(5)  评论(0)    收藏  举报