介绍
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安装向导
VitePress 附带一个命令行设置向导，可帮助您搭建基本项目的基架。安装后，通过运行以下命令启动向导：
npx vitepress init您会看到几个简单的问题：
┌ 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注入以下脚本:
{
...
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
},
...
}运行
npm run docs:dev配置
在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' }
]
}
})
部署到 Github Pages + Gitee Pages
- 修改
config的base- 如果要部署到 https://<USERNAME>.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",
})- 创建 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
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。
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，我们成功搭建了一个功能强大、美观专业的文档系统，为用户提供了更好的阅读和搜索体验。
0 个评论
要回复文章请先登录或注册