使用vitepress构建组件库文档
使用vitepress构建组件库文档前期调研Vitepress官方文档:https://vitepress.vuejs.org/Vitepress是在Vite之上构建的Vue驱动的静态站点生成器。Vitepress 被称为“ Vuepress的小弟弟”,它比同类产品具有一些优势。建立在Vite而非Webpack上,因此启动时间,热重装等更快使用Vue3来减少JS的有效负载轻量级Vitepress
·
使用vitepress构建组件库文档
前期调研
Vitepress
-
官方文档:
https://vitepress.vuejs.org/
- Vitepress是在Vite之上构建的Vue驱动的静态站点生成器。
Vitepress
被称为“ Vuepress的小弟弟”
,它比同类产品具有一些优势。
-
建立在Vite而非Webpack上,因此启动时间,热重装等更快
-
使用Vue3来减少JS的有效负载
-
轻量级
Vitepress 能够实现这些目标的一个原因是,它比Vuepress 更具体,而 Vuepress在过去几年里变得更加复杂。
虽然不打算完全取代Vuepress作为 Vue 的静态网站生成器,但 Vitepress 提供了一种轻量级的替代方案。 对于大多数项目,例如文档和简单站点,Vitepress的特殊性和简约性将使开发变得轻而易举
官方文档提示
- VitePress 目前处于 0.x 状态。它已经适合开箱即用的文档使用,但配置和主题 API 可能仍会在次要版本之间发生变化。
- 这个早期的
WIP
(可理解成在制品
),目前主要精力专注于Vite
的稳定和功能的完整,对于一些serious
的事不建议使用它!
PS:偶然发现element-plus的组件库文档就是使用VitePress
,放心用住!!!
优势
- 它相当于
VuePress
,当它将Vue2
换成Vue3
,把webpack
换成vite
,因此:- 它有
VuePress
的所有优点;如:可以在md
里面混合vue
组件等; - 具有
Vite
的速度;如:可以秒开一个VitePress
开发服务器以及md的编辑也会瞬间更新 - 利用
Vue3
的一些高阶特性,做了一些更细致的优化;如避免纯静态内容的double payload
(双重负载)和hydration
开销
- 它有
- 两款支持vitepress的demo展示插件
vitepress-theme-demoblock
和vitepress-for-component
。
安装VitePress
- 初始化
- 如果
mkdir && echo '# Hello VitePress' > docs/index.md
没有效果,可以自己手动创建
- 如果
yarn init
yarn add --dev vitepress
mkdir && echo '# Hello VitePress' > docs/index.md
- 添加命令到
package.json
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:serve": "vitepress serve docs",
},
- 启动本地服务
http://localhost:3000/
可以看到初始化的页面
yarn docs:dev
配置VitePress
- 在
docs
目录下创建.vitepress
目录即可开始设置配置- 在
.vitepress
中新建config.js
文件进行配置 - 实现侧边栏,导航栏及搜索框
- 在
module.exports = {
title: 'Kylin',
description: 'Just playing around.',
lang: 'en-US',
themeConfig: {
// 展示搜索框
algolia: {
appKey: '',
indexName: '',
searchParameters: {
faeFilters: ['tags:guide,api']
}
},
nav: [{
text: '首页',
link: '/',
},
{
text: 'GitHub',
link: 'https://github.com/lxKylin/vitepressdemo',
},
],
// 侧边栏
sidebar: {
'/': getDemoSidebar(),
}
},
markdown: {
config: (md) => {
const {
demoBlockPlugin
} = require('vitepress-theme-demoblock')
md.use(demoBlockPlugin)
}
}
}
function getDemoSidebar() {
return [
{
text: "介绍"
},
{
text: "更新日志",
children: [{
text: "新特性",
link: "/components/log/"
}]
},
{
text: "开发指南",
children: [{
text: "安装"
}]
},
{
text: "快速开始",
link: "/"
},
{
text: "基础组件",
children: [{
text: "Button 按钮",
link: "/components/button/"
},
{
text: "Icon 图标",
link: "/components/icon/"
},
],
},
{
text: "布局组件",
},
]
}
- 效果图如下
创建Button按钮展示
- 创建
docs/components/button/index.md
文件- 可以在该文件中使用
markdown
语法随便写入内容
- 可以在该文件中使用
// docs/components/button/index.md
# Button 按钮
```vue
<template>
<button>按钮</button>
</template>
```
- 效果图
组件显示与代码的展开关闭
-
需要用到
vitepress-theme-demoblock
插件npm install -D vitepress-theme-demoblock # or yarn add -D vitepress-theme-demoblock
-
这个插件不可以避免展示组件和代码需要重复写两遍的问题
- 将这个插件,注册到
vitepress
的config.js
中(上述代码中已经写入)
module.exports = { markdown: { config: (md) => { const { demoBlockPlugin } = require('vitepress-theme-demoblock') md.use(demoBlockPlugin) } } }
- 将这个插件,注册到
-
注入主题与插件
- 在
docs/.vitepress/theme/index.ts
中注册- 其中
register-components.js
不需要自己创建,在package.json
中注入脚本,执行脚本自动生成在docs/.vitepress/theme
目录下
- 其中
"scripts": {
"register:components": "vitepress-rc"
}
yarn register:components
// 导入vitepress-theme-demoblock主题,并注册组件(包含主题中默认的组件)。
import Theme from 'vitepress/dist/client/theme-default'
// 导入主题样式
import 'vitepress-theme-demoblock/theme/styles/index.css'
// 导入插件的主题
import { registerComponents } from './register-components.js'
export default {
...Theme,
enhanceApp({ app }) {
registerComponents(app)
}
}
效果
- 在需要展示的
demo
中的index.md
文件中使用特定的语法包裹代码,可以自动生成组件demo
展示- 比如在
docs/components/button/index.md
中 :::demo
是描述部分- 使用的是最初的
button
,最初只为展示出组件,后续再研究怎么封装
- 比如在
# Button 按钮
:::demo 使用`type`,`plain`,`round`来定义 Button 的样式
```vue
<template>
Small
<button style="color: red">按钮1</button>
Middle
<button type="size">按钮2</button>
Large
<button>按钮3</button>
Disabled
<button disabled>按钮4</button>
</template>
```
:::
- 具体代码可见GitHub:https://github.com/lxKylin/vitepressdemo
更多推荐
已为社区贡献2条内容
所有评论(0)