使用VuePress2搭建基于Vue3的组件库，并部署到GitHub Pages
使用VuePress2搭建基于Vue3的组件库，并部署到GitHub Pages
完成后的效果图展示：
使用vue-cli进行项目构建
一、使用命令 vue create m-baseui 快速初始化一个项目
这里参考我写的上一篇：
基于Vue3开发自己的组件库
二、打开VuePress官网，切换到v2版本，快速上手中可以看到
在一个现有项目中使用 VuePress 管理文档，直接从步骤3开始
步骤3: 将 VuePress 安装为本地依赖
npm install -D vuepress@next 或者 yarn add -D vuepress@next
步骤4: 在 package.json 中添加一些 scripts
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
步骤5：在本地启动服务器
npm run docs:dev
启动后项目会多出一个docs文件夹
打开运行出来的页面，发现页面404，别急，这是因为你还没有入口文件
在docs文件夹下新建 README.md（默认为站点首页）， 里面随便写点什么，再去看就有内容了
.vuepress下的.cache 和.temp 不用管它，把它们加入到.gitignore里面去
现在，你应该已经有了一个简单可用的 VuePress 文档网站
现在我们来进行文件配置
经过一番配置后，docs文件夹初始化后的目录结构如下：
描述：
docs/.vuepress: 存放全局的配置、组件、静态资源等。docs/.vuepress/config: 存放页眉导航栏和子页面侧栏的配置文件。docs/.vuepress/public: 静态资源目录。docs/.vuepress/config.js: 配置文件的入口文件。docs/README.md: 文档的入口页面。
入口README.md配置
---
home: true
heroImage: /images/timg2.jpg
heroText: 基于Vue3的轻量级UI组件库
tagline: 更小的体积，更快的响应，更强的拓展性
actions:
- text: 快速上手 →
link: /componentDocs/Install
type: primary
features:
- title: 简洁至上
details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- title: Vue驱动
details: 享受 Vue 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
- title: 高性能
details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
---
config.js配置
const { defaultTheme } = require('vuepress')
module.exports = {
title: 'm-baseui',
description: 'm-baseui Component library with Vue3',
base: '/', // 这是部署到github相关的配置
markdown: {
code: {
lineNumbers: false // 代码块显示行号
}
},
theme: defaultTheme({
// 在这里进行配置
navbar: [],
sidebar: []
})
}
注意：每次配置config.js文件都需要重新运行一下项目
完成上述配置后，查看运行效果：
接下来配置导航栏和侧边栏
navbar.js导航栏配置
1、在docs/.vuepress/config/navbar.js中做出如下配置
module.exports = [
{
text: '首页',
link: '/'
},
{
text: '组件',
link: '/componentDocs/Install'
},
{
text: '博客指南',
children: [{
text: '掘金',
link: 'https://juejin.cn/'
},
{
text: '博客园',
link: 'https://www.cnblogs.com/wangdashi/'
}
]
},
{
text: 'github',
link: 'https://github.com/m-baseui/m-baseui'
}
]
描述：
-
text： 显示在导航栏上的文字信息
-
link： 路由地址显示的页面（类似于router中的component）会自动寻址到指定目录下的
README.md，把它作为主入口显示出来。link字段也可以配置线上地址，点击后跳转到线上页面 -
children： 子路由的嵌套信息，可多层嵌套
2、将navbar.js文件引入config.js中
const navbar = require('./config/navbar')
const { defaultTheme } = require('vuepress')
module.exports = {
title: 'm-baseui',
description: 'm-baseui Component library with Vue3',
base: '/', // 这是部署到github相关的配置
markdown: {
code: {
lineNumbers: false // 代码块显示行号
}
},
theme: defaultTheme({
// 在这里进行配置
navbar,
sidebar: []
})
}
navbar配置完成后效果如下：
至此我们的导航栏配置工作完成。
接下来我们通过配置sidebar.js，实现侧边栏切换功能。
sidebar.js侧边栏配置
1.在docs文件夹下新建componentDocs
2.在docs/.vuepress/config/sidebar.js中做出如下配置
module.exports = [
{
text: '快速上手',
children: [
{
text: '安装使用',
link: '/componentDocs/Install'
}
]
},
{
text: '常规',
children: [
{
text: 'Layout 布局',
link: '/componentDocs/Layout'
}
]
},
{
text: '通用',
children: [
{
text: 'Button 组件',
link: '/componentDocs/Button'
},
{
text: 'Input 组件',
link: '/componentDocs/Input'
}
]
}
]
3.将sidebar.js文件引入config.js中
const navbar = require('./config/navbar')
const sidebar = require('./config/sidebar')
const { defaultTheme } = require('vuepress')
module.exports = {
title: 'm-baseui',
description: 'm-baseui Component library with Vue3',
base: '/', // 这是部署到github相关的配置
markdown: {
code: {
lineNumbers: false // 代码块显示行号
}
},
theme: defaultTheme({
// 在这里进行配置
navbar,
sidebar
})
}
sidebar配置完成后效果如下：
配置完成后，就可以正常切换左侧栏了，至此页面搭建工作完成。
在VuePress中展示Vue组件
我们平时在项目中使用Element，需要在main.js中引入Element，并使用Vue.use(Element) 进行调用，才能够在vue组件中使用Element的组件，那么如何在vuepress中使用组件库呢？
此时client.js文件就出来了，如果你想做一些vue应用级别的配置，就需要在这个文件里配置。
一、在.vuepress目录下创建 client.js 文件 和 components 文件夹
描述：
client.js ：用来增强客户端配置（v1版本中名称是enhanceApp.js，记得v2之前有版本是clientAppEnhance.js，最新v2 beta.45变成了client.js，不知道后面还会不会改，一切以官网为准），
components：用来放vue组件
去官网查看：https://v2.vuepress.vuejs.org/zh/advanced/cookbook/usage-of-client-config.html
二、client.js配置如下：
import { defineClientConfig } from '@vuepress/client'
// 导入组件库
import mBaseui from '../../packages'
export default defineClientConfig ({
enhance({ app }){
// app 是由 createApp 创建的 Vue 应用实例
app.use(mBaseui)
}
})
三、识别.vue文件
在Vuepress1.0中，md文件能自动识别导出的.vue文件，Vuepress2.0中需要安装插件并做好配置
步骤1： 安装 @vuepress/plugin-register-components 插件
yarn add @vuepress/plugin-register-components@next -D
步骤2： config.js中配置修改如下：
const navbar = require('./config/navbar')
const sidebar = require('./config/sidebar')
const { defaultTheme } = require('vuepress')
const { registerComponentsPlugin } = require('@vuepress/plugin-register-components')
const { path } = require('@vuepress/utils')
module.exports = {
title: 'm-baseui',
description: 'm-baseui Component library with Vue3',
base: '/', // 这是部署到github相关的配置
markdown: {
code: {
lineNumbers: false // 代码块显示行号
}
},
theme: defaultTheme({
// 在这里进行配置
navbar,
sidebar
}),
plugins: [
registerComponentsPlugin({
componentsDir: path.resolve(__dirname, './components'),
})
]
}
步骤3：components文件夹下新建Button.vue
<template>
<m-row>
<m-button>默认按钮</m-button>
<m-button type="primary">主要按钮</m-button>
<m-button type="success">成功按钮</m-button>
<m-button type="danger">危险按钮</m-button>
<m-button type="info">信息按钮</m-button>
<m-button type="warning">警告按钮</m-button>
<m-button type="text">文本按钮</m-button>
</m-row>
<m-row>
<m-button round>默认按钮</m-button>
<m-button type="primary" round>主要按钮</m-button>
<m-button type="success" round>成功按钮</m-button>
<m-button type="danger" round>危险按钮</m-button>
<m-button type="info" round>信息按钮</m-button>
<m-button type="text" round>文本按钮</m-button>
</m-row>
</template>
步骤4：docs/componentDocs/Button.md 中直接引入Button.vue组件
# Button 按钮 #### 常用 button 按钮 ## 基本使用 #### button 按钮的基本使用 <br/> <Button></Button>
如果组件是在components的子文件夹中，就需要将其添加到组件名称之前，例如：
对于存储在 .vuepress/components/Button/Demo.vue 的组件，使用方式为：
<Button-Demo />
完成后看效果：
VuePress部署
接下来我们部署到免费的 GitHub Pages 上
查看 VuePress官网--->部署--->GitHub Pages,
v2版本部署 GitHub Pages 只介绍了以 GitHub Actions 为例，这里我们也以这种方式部署
一、在github上新建项目 m-baseui
把本地创建的m-baseui与github关联，并上传到github上
git init git add ./ git commit -m "init" git remote add origin https://github.com/m-baseui/m-baseui.git git branch -M master git push -u origin master
提交完成后，刷新github，看到已经把我们的项目m-baseui 成功上传到github上了
二、在 docs/.vuepress/config.js 中设置正确的 base
module.exports = {
title: 'm-baseui',
description: 'm-baseui Component library with Vue3',
base: '/m-baseui', // 这是部署到github相关的配置
markdown: {
code: {
lineNumbers: false // 代码块显示行号
}
},
theme: defaultTheme({
// 在这里进行配置
navbar,
sidebar
}),
plugins: [
registerComponentsPlugin({
componentsDir: path.resolve(__dirname, './components'),
})
]
}
三、打包，运行命令会在docs文件夹下产生一个dist文件
npm run docs:build
（实际上部署就是将打包的.vuepress/dist文件上传到远程仓库地址）
四、创建 .github/workflows/xxx.yml 文件来配置工作流
vuepress官网点击展开配置样例，看下代码给到我们一些信息，
大概意思就是，每当我们push 到main 分支时，会触发部署（如果你要push到master上，就改成master）
运行yarn docs:build 时，会把之前产生的dist文件部署到gh-pages 分支上，
关于GITHUB_TOKEN
github头像点开选择"Settings"，然后左边列表最下面选择 “Developer settings”，进入设置后选择"Personal access tokens"，生成一个token，把这个token复制保存下来
复制这个token到你项目仓库的Settings --->Secrets--->Actions---> New repository secret，name可以自己取（我取的是ACCESS_TOKEN）。value是你刚才复制的token。
点击项目Actions ，设置一个工作流workflows yml，把vuepress官网的配置样例修改下粘贴进去
修改的地方：
1、我是提交到master，就把main改成了master
2、把node版本改成自己的node版本
3、 GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}
提交后，你的项目就多了一个文件.github/workflows，
在你的项目中执行git pull 拉取下来，后面你修改代码执行push操作时，就会把dist文件部署到gh-pages 分支上，
切换到gh-pages分支，可以看到dist文件已经上传到github上了
点击Settings---->Pages---Source 切换到 gh-pages分支保存，
https://m-baseui.github.io/m-baseui/就是部署到GitHub Pages上的链接
部署成功，点击链接查看：https://m-baseui.github.io/m-baseui/
