十分钟使用vitepress+github action+gitee pages 搭建你的专属文档_使用vitepress搭建githubpages

介绍

VitePress 是 VuePress 的精神继承者。最初的 VuePress 基于Vue 2和webpack。在VitePress内部使用了Vue 3和Vite，这使得VitePress在开发体验、生产性能、默认主题的精细化和更灵活的自定义API方面提供了显著的改进。本文将介绍使用VitePress搭建uni-app路由库uni-mini-router的文档，并通过github action实现自动化部署到github pages与gitee pages。

创建项目

安装

关于安装配置的问题，vitepress目前还没有稳定的版本，所以可能会有所变动，推荐还是看一下文档然后进行创建。

mkdir your-project
npm init
yarn add -D vitepress
1
2
3

安装向导

VitePress 附带一个命令行设置向导，可帮助您搭建基本项目的基架。安装后，通过运行以下命令启动向导：

npx vitepress init
1

您会看到几个简单的问题：

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  uni-mini-router（你的项目名称）
│
◇  Site description:
│  一个基于vue3+typescript的uni-app路由库（你的项目介绍）
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
└  Done! Now run npm run docs:dev and start writing.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

执行完本步骤后，将会向你的package.json注入以下脚本:

{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}
1
2
3
4
5
6
7
8
9

运行

npm run docs:dev
1

配置

在docs/.vitepress文件夹中有一个 config.mts 文件，我们可以在这里配置文档项目，配置项参考配置。

import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  title: "uni-mini-router",
  description: "一个基于vue3+typescript的uni-app路由库",
  themeConfig: {
    // https://vitepress.dev/reference/default-theme-config
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Examples', link: '/markdown-examples' }
    ],

    sidebar: [
      {
        text: 'Examples',
        items: [
          { text: 'Markdown Examples', link: '/markdown-examples' },
          { text: 'Runtime API Examples', link: '/api-examples' }
        ]
      }
    ],

    socialLinks: [
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
    ]
  }
})

1
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

部署到 Github Pages + Gitee Pages

1. 修改config的base

• 如果要部署到 https://.github.io/，则可以省略 base，因为它默认为 “/”。
• 如果您正在部署到 https://<USERNAME>.github.io/<REPO>/，例如，您的存储库位于 github.com/<REPO>/，然后将 base 设置为 /<REPO>/

// 示例
import { defineConfig } from 'vitepress'

export default defineConfig({
  base: "/uni-mini-router/", // 这里为仓库名
  title: "uni-mini-router",
})
1
2
3
4
5
6
7

2. 创建 Github Action 部署Github Pages并同步至Gitee Pages

Github Pages在国内的访问速度并不理想，而Gitee则没有类似Github Action的功能且标准版Gitee Pages不支持自动部署，所以我们通过Github Action 将文档部署Github Pages并同步至Gitee Pages。

在项目根目录下创建.github文件夹，.github中创建workflows文件夹并创建文件deploy.yml

name: Deploy VitePress site to Pages

on:
  push:
    tags:
      - '*'

  workflow_dispatch:

jobs:
  deploy-and-sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 
声明：本文内容由网友自发贡献，不代表【wpsshop博客】立场，版权归原作者所有，本站不承担相应法律责任。如您发现有侵权的内容，请联系我们。转载请注明出处：https://www.wpsshop.cn/w/Gausst松鼠会/article/detail/574708