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

介绍

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目前还没有稳定的版本，所以可能会有所变动，推荐还是看一下文档然后进行创建。

sh 复制代码

mkdir your-project
npm init
yarn add -D vitepress

安装向导

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

sh 复制代码

npx vitepress init

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

sh 复制代码

┌  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.

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

json 复制代码

{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}

运行

sh 复制代码

npm run docs:dev

配置

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

ts 复制代码

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' }
    ]
  }
})

部署到 Github Pages + Gitee Pages

修改config的base

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

ts 复制代码

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

export default defineConfig({
  base: "/uni-mini-router/", // 这里为仓库名
  title: "uni-mini-router",
})

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

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

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

yml 复制代码

name: Deploy VitePress site to Pages

on:
  push:
    tags:
      - '*'

  workflow_dispatch:

jobs:
  deploy-and-sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v4
        with:
          ref: 'master'

      - name: Install yarn
        run: corepack enable

      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'yarn'

      - name: Install dependencies
        run: yarn install

      - name: Build Site
        run: npm run docs:build

      # 将文档产物提交到gh-pages分支
      - name: Deploy for Gitee 🚀
        uses: JamesIves/github-pages-deploy-action@v4.4.1
        with:
          branch: gh-pages
          folder: docs/.vitepress/dist
          # enable single-commit to reduce the repo size
          single-commit: true
          clean: true

      - name: Sync to Gitee
        uses: wearerequired/git-mirror-action@v1.2.0
        env:
          SSH_PRIVATE_KEY: ${{ secrets.GITEE_RSA_PRIVATE_KEY }}
        with:
          # GitHub 仓库地址
          source-repo: git@github.com:Moonofweisheng/uni-mini-router.git
          # Gitee 仓库地址
          destination-repo: git@gitee.com:Moonofweisheng/uni-mini-router.git
  
      - name: Build Gitee Pages
        uses: yanglbme/gitee-pages-action@main
        with:
          # 替换为你的 Gitee 用户名
          gitee-username: Moonofweisheng
          # 注意在 Settings->Secrets 配置 GITEE_PASSWORD
          gitee-password: ${{ secrets.GITEE_PASSWORD }}
          # 注意替换为你的 Gitee 仓库，仓库名严格区分大小写，请准确填写，否则会出错
          gitee-repo: Moonofweisheng/uni-mini-router
          # 要部署的分支，默认是 master，若是其他分支，则需要指定（指定的分支必须存在）
          branch: gh-pages

其中GITEE_RSA_PRIVATE_KEY是私钥，生成步骤如下：

在 GitHub 项目的Settings -> Pages路径下配置Build and deployment，source选Deploy from a branch，branch选择gh-pages，路径选择/root。
在 Gitee 项目的服务 -> Gitee Pages中设置部署分支为gh-pages，部署目录则不用填。
在命令行终端或 Git Bash 使用命令 ssh-keygen 生成 SSH Key，连续三次回车。生成的 id_rsa 是私钥，id_rsa.pub 是公钥。
在 GitHub 项目的Settings -> Secrets路径下配置好命名为 GITEE_RSA_PRIVATE_KEY 密钥。GITEE_RSA_PRIVATE_KEY 存放 id_rsa 私钥。
在 GitHub 的个人设置页面SSH and GPG keys 配置 SSH 公钥（即：id_rsa.pub），命名任意。
在 Gitee 的个人设置页面SSH 公钥配置 SSH 公钥（即：id_rsa.pub），命名可任意。
在 GitHub 项目的 Settings -> Secrets 路径下配置好命名为 GITEE_RSA_PRIVATE_KEY 和 GITEE_PASSWORD 的两个密钥。其中：GITEE_RSA_PRIVATE_KEY 存放 id_rsa 私钥；GITEE_PASSWORD 存放 Gitee 帐号的密码。
在 GitHub 项目的Settings -> Actions -> General路径下配置Fork pull request workflows from outside collaborators为Require approval for first-time contributors who are new to GitHub，将Workflow permissions配置为Read and write permissions。

至此我们就实现了通过Github Action 部署Github Pages并同步至Gitee Pages

Algolia 搜索

vitepress自带站内搜索功能有限，所以我推荐使用Algolia搜索，Algolia 提供了一套强大的搜索功能，包括全文搜索、过滤、排序、分页和高亮等。它还支持多语言搜索、拼写纠正和近义词处理，以提供更准确和相关的搜索结果。

申请 Docsearch

首先，我们打开Docsearch的申请地址，填写网站地址、邮箱和仓库地址等信息，这里注意，文档内容和代码要是开源且可以公开访问的。申请过后我们会收到三封邮件，按照指示即可完成申请。

配置文档

在文档的config中增加themeConfig，配置search。

ts 复制代码

export default defineConfig({
  base: "/uni-mini-router/",
  title: `Uni Mini Router`,
  ...
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '你的appid',
        apiKey: '你的APIkey，注意是搜索的key',
        indexName: '你的indexName',
      },
    },
  },
  ...
})

执行爬虫

我们这里使用Algolia提供的爬虫进行爬取，访问地址，选中我们创建的index，然后点击右上角的【Restart crawling】执行。当然即使我们不手动执行，Algolia也会定期对我们的文档进行爬取的。

总结

通过使用VitePress、GitHub Pages和Gitee Pages，以及GitHub Actions，我们成功搭建了一个专属文档的自动化部署系统。VitePress作为VuePress的继任者，提供了更好的开发体验和性能表现。我们使用VitePress创建了一个uni-app路由库的文档，并通过GitHub Actions实现了自动部署到GitHub Pages和Gitee Pages。

为了解决GitHub Pages在国内访问速度不理想的问题，我们使用GitHub Actions将文档部署到GitHub Pages，并通过Gitee Pages实现了同步部署。这样，无论用户在国内还是国外，都可以快速访问到我们的文档。

为了提供更好的搜索功能，我们申请了Algolia的Docsearch服务，并在配置文件中添加了搜索功能的相关配置。通过执行Algolia提供的爬虫，我们可以定期更新文档的搜索索引，以提供准确和相关的搜索结果。

总的来说，通过使用VitePress、GitHub Pages和Gitee Pages，以及GitHub Actions和Algolia，我们成功搭建了一个功能强大、美观专业的文档系统，为用户提供了更好的阅读和搜索体验。

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

介绍

创建项目

安装

安装向导

运行

配置

部署到 Github Pages + Gitee Pages

Algolia 搜索

申请 Docsearch

配置文档

执行爬虫

总结

链接