搭建组件库文档
# 前言
当组件库开发完毕后,需要提供一份完善的文档,方便用户更好的上手组件库。
# vuepress介绍
MSSUI文档 (opens new window) 使用 vuepress (opens new window)搭建。vueperss 本质上就是一个vue项目,只不过是可以使用 markdown (opens new window)语法,并且可以在 markdown 中可以使用vue,这是vue作者尤雨溪写来给vue搭建官放文档所用的。可以说,结合vue的能力,vuepress 的功能十分强大。
# 目录介绍
vuepress 如何使用,自行去官网查看即可,官网文档已经说得很仔细了。这里主要说下 mssui
的官网文档是如下搭建的。
mssui
的文档项目在 src/docs
下:
├── .vuepress
│ ├── components
│ ├── dist
│ ├── public
│ ├── config.js
│ ├── enhanceApp.js
├── component
└── zh
├── README.md
2
3
4
5
6
7
8
9
vuepress 遵循的是 约定大于配置
的开发原则,使用 vueprss 的时候只需要遵循相关的约定,就是最佳的实践。比如上面的目录结构就是官方约定好的开发目录:
- components 放置全局的vue组件
- dist 打包后默认目录
- public 静态资源放置目录
- config.js 配置文件的入口文件,也可以是 YML 或 toml
- enhanceApp.js 客户端应用的增强
- component 放置每个组件的文档(.md文件)
- README.md 主页说明
- zh 中文语言放置文件
下面我们详细说说搭建一个组件库的文档具体应该如何做。
# 配置config.js
使用 vuepress 搭建的网站的基本配置文件是 .vuepress/config.js
,MSSUI
的基本配置如下:
const path = require('path')
module.exports = {
title: 'MSS-UI', // 首页标题
description: 'A UI library build by Vue 2.0', // 网站的描述
base: '/', // 服务器访问静态资源的跟路径
head: [ // 网站标题栏的相关设置
['link', { rel: 'icon', href: '/mssui.png' }]
],
themeConfig: { // 主题设置
nav: [
{ text: '首页', link: '/' },
{ text: '文档', link: '/component/Instroduce' },
{ text: 'GitHub', link: 'https://github.com/MssText/mssui' }
],
sidebar: [ // 侧边栏的相关设置
{
title: '开发指南',
collapsable: false,
children: [
'/component/Instroduce',
'/component/Start',
]
},
{
title: '组件',
collapsable: false,
children: [
{
title: '通用',
collapsable: false,
children: [
'/component/Button',
'/component/Message',
'/component/Alert',
'/component/Card',
'/component/Link',
'/component/Backtop',
]
}
]
}
]
},
configureWebpack: { // 修改内部的webpack设置
resolve: {
alias: {
"@": path.resolve(process.cwd(), "./src"),
}
}
},
locales: { // 文档国际化设置
// 键名是该语言所属的子路径
// 作为特例,默认语言可以使用 '/' 作为其路径。
'/': {
lang: 'en-US', // 将会被设置为 <html> 的 lang 属性
},
'/zh/': {
lang: '简体中文',
title: 'MSS-UI',
description: '基本Vue2.0的组件库'
}
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
为了更好的说明上面配置项对应的效果,我们用一张图进行说明:
侧边栏的配置图示如下:
sidebar
中的 children
配置每个组件的md
文件的相对路径。
# 书写README文件
vuepress根目录下的 README
文件,是作为文档的主页说明,比如 MSSUI
文档的 README
文件:
---
home: true // 是否是主页
heroImage: /mssui.png // 首页大图
actionText: 快速上手 → → // 从主页进入文档操作的自定义提示文案
actionLink: /component/Instroduce // 跳转的页面
features:
- title: 组件库工程化 // 首页的关键词
details: 从0到1搭建一个组件库,工程化如何搭建。 // 描述
- title: 组件库性能优化
details: 面对不同维度场景的需求,如何提供全局加载和按需加载能力。
- title: 组件库样式隔离
details: 组件之间的样式如何使用BEM规范进行隔离。
footer: MIT Licensed | Copyright © 2021-present MSS // 底部的信息
---
2
3
4
5
6
7
8
9
10
11
12
13
14
书写文档的主页,其实就是进行一些配置,更多的配置可以去vuepress配置 (opens new window)查看。为了更好的理解上面的配置,我们用MSSUI
首页的图标示一下:
# 文档中使用MSSUI组件
应用级别的配置就需要在 enhanceApp.js
中配置,相当于Vue项目中的入口文件 main.js
:
import components from '@/components.js'
import Message from '@/packages/message/index'
import '../../theme/index.scss'
export default ({
Vue, // VuePress 正在使用的 Vue 构造函数
}) => {
components.forEach(component => {
Vue.component(component.name, component);
})
Vue.prototype.$message = Message
}
2
3
4
5
6
7
8
9
10
11
12
将 MSSUI
的组件导入,然后全局注册组件。
注意
Message需要手动挂载到Vue实例上
这样,我们就可以全局的使用 MSSUI
的组件了。然后我们现在就可以明确了,比如我们想书写 button
组件的文档,我们的流程是:
- 在
.vuepress/components
新增button
组件需要展示的组件代码(可以直接使用MSSUI
的组件,前面已经注册) - 在
.vuepress/component
新增button
组件具体的文字说明,也就是放置.md
文件。
这样,文档基本的配置和流程我们已经搞清楚了。