基于VuePress2开发文档自部署及嵌入VUE项目

最近在搞前端开发帮助文档，转了一圈发现Vue提供了一个高性能的、Vue驱动的静态网站生成框架-VuePress。VuePress 是一个以 Markdown 为中心的静态网站生成器。你可以使用 Markdown 来书写内容（如文档、博客等），然后 VuePress 会生成一个静态网站来展示它们。废话不多说了，直接上手！

项目配置

项目基础配置我是参考的这篇文章-https://www.cnblogs.com/wangdashi/p/16308107.html，大家可以按他的步骤一一配置，我只说一下一些新的配置：

展示UI组件

1.配置组件库

在docs/.vuepress/client.js文件中引入ElementPlus组件库，然后挂载在Vue上。

import { defineClientConfig  } from '@vuepress/client'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
 
export default defineClientConfig ({
  enhance({ app }){
    // app 是由 createApp 创建的 Vue 应用实例
    app.use(ElementPlus)
  }
})

2.自动导入UI

首先安装 @vuepress/plugin-register-components 插件

npm add @vuepress/plugin-register-components@next -D

在docs/.vuepress/config.js文件配置一下：

plugins: [
     [ 
      registerComponentsPlugin({
        componentsDir: path.resolve(__dirname, './components'),
      })
    ]
  ]

然后在components/下创建vue组件文件：

<template>
  <div class="example-basic">
    <el-time-picker v-model="value1" placeholder="Arbitrary time" />
    <el-time-picker
      v-model="value2"
      arrow-control
      placeholder="Arbitrary time"
    />
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value1 = ref()
const value2 = ref()
</script>

<style>
.example-basic .el-date-editor {
  margin: 8px;
}
</style>

最后在md文件中直接引用组件文件名：

<TimePicker></TimePicker>

效果：

GitHub部署

我是一键部署到 gh-pages 分支，然后实现部署。

1.配置base

config.js文件里的base，必须跟你的仓库名一致！！

export default defineUserConfig({
  bundler: viteBundler(),
  lang: 'zh-CN',
  title: '帮助中心',
  description: '产品使用帮助文档',
  base: '/Your repository/',
}

2.配置gh-pages

先安装

npm install --save-dev gh-pages

在 package.json 加脚本：

  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs",
    "deploy": "npm run docs:build && gh-pages -d docs/.vuepress/dist -b gh-pages"
  }

运行部署：

npm run deploy

gh-pages 会把 docs/.vuepress/dist 的内容推到仓库的 gh-pages 分支（自动建立），部署完一般可通过 https://USERNAME.github.io/REPO/ 访问（几分钟生效）。

1. 在 GitHub 仓库设置（一般自动）：

• 到 Repo → Settings → Pages，查看 Source 是否为 gh-pages branch。如果不是，手动设置为 gh-pages 即可。

3.自动更新

部署成功之后再修改内容，提交仓库后再使用部署命令即可实现更新。

部署成功，欢迎点击链接查看：帮助中心

嵌入VUE项目

嵌入已有的项目可以使用多种方法：

1.将文档项目部署后直接在已有项目中使用链接打开；

2.将文档项目打包然后放进现有项目中的/public/docs目录下，然后在 Vue3 中使用 <iframe> 嵌入：

<template>
  <iframe src="/docs/index.html" style="width:100%;height:100vh;border:none;"></iframe>
</template>