十分钟使用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。

创建项目

使用nvm安装node

# 查看可用版本
$nvm list avaliable
# 安装 node
$nvm install 18.16.0
# 切换node
$nvm use 18.16.0

创建vitepress项目

# 全局安装vitepress
$npm install -D vitepress
# 创建项目文件夹
$mkdir notes
# 使用vitepress自带的npx初始化 - VitePress 附带一个命令行设置向导，可帮助您搭建基本项目的基架。安装后，通过运行以下命令启动向导：
$npx vitepress init
# 运行
$npm run docs:dev

推送项目到github

# 在项目根目录下初始化git
$git init
# 添加远程仓库地址
$git remote add origin git@github.com:yourname/note.git
# 创建.gitignore文件 并配置如下:
.DS_Store
.vscode
*lock.*
.git/
node_modules/
# 提交代码到远程仓库
#检查文件状态
$git status
#添加文件被git管理
$git add .
#提交
$git commit -m 'init'
#推送到远程
$git push origin

配置ssh公私钥

详细配置见

1.1 生成SSH公私钥:

在命令行终端或 Git Bash 使用命令 ssh-keygen 生成 SSH Key，连续三次回车。生成的 id_rsa 是私钥，id_rsa.pub 是公钥 sh $ssh-keygen -t rsa -C "youremail@example.com" -f "gitee_id_rsa"

1.2 添加私钥

在 GitHub 项目的Settings -> Secrets路径下配置好命名为 GITEE_RSA_PRIVATE_KEY 密钥, GITEE_RSA_PRIVATE_KEY 存放 id_rsa 私钥;
在 GitHub 项目的 Settings -> Secrets 路径下配置好命名为 GITEE_RSA_PRIVATE_KEY 和 GITEE_PASSWORD 的两个密钥, 其中：GITEE_RSA_PRIVATE_KEY 存放 id_rsa 私钥；GITEE_PASSWORD 存放 Gitee 帐号的密码。

1.3 添加公钥

在 GitHub 的个人设置页面SSH and GPG keys 配置 SSH 公钥（即：id_rsa.pub），命名任意;
在 Gitee 的个人设置页面SSH 公钥 配置 SSH 公钥（即：id_rsa.pub），命名可任意。
ddd

在 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部署脚本

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

目的是: 在之后每次有 Push 请求的时候，该脚本就会自动执行，完成云端Build静态文件，部署到 gh_pages 分支，然后将代码同步到 Gitee 的镜像仓库，并且自动执行 Pages 的 Update 操作！！！

deploy.yml:

yml

name: Deploy VitePress site to Pages
# 触发条件：在push 到 master 分支后
on:
  push:  
    # 推送任意tags或者master分支推送的时候触发任务
    tags:  
      - '*' 
    branches:
      - master 

  workflow_dispatch: 
# 任务
jobs:
  # This workflow contains a single job called "build"
  deploy_and_sync:
    # 在哪个操作系统下 - 服务器环境：最新版ubuntu
    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: 'npm'

      - name: Install dependencies  
        # run: yarn install  
        # run: npm ci
        run: npm install
        
      - name: Build Site  
        run: npm run docs:build  
      # 将文档产物提交到 gh-pages 分支  
      - name: Deploy for Github  
        uses: JamesIves/github-pages-deploy-action@v4.4.1  
        with:  
          branch: gh-pages  
          folder: .vitepress/dist  
          # enable single-commit to reduce the repo size  
          single-commit: true  
          clean: true 
      # # 同步到gitee仓库
      # - name: Sync to Gitee
      #   uses: wearerequired/git-mirror-action@master
      #   env:
      #     # 注意在 Settings->Secrets 配置 GITEE_RSA_PRIVATE_KEY
      #     SSH_PRIVATE_KEY: ${{ secrets.GITEE_RSA_PRIVATE_KEY }}
      #   with:
      #     # 注意替换为你的 GitHub 源仓库地址 - SSH URL of the source repo
      #     source-repo: git@github.com:sglkfdog/tech_notes.git
      #     # 注意替换为你的 Gitee 目标仓库地址 - SSH URL of the destination repo
      #     destination-repo: git@gitee.com:freexll/tech_notes.git
      # - name: Build Gitee Pages
      #   uses: yanglbme/gitee-pages-action@main
      #   with:
      #     # 注意替换为你的 Gitee 用户名
      #     gitee-username: freexll
      #     # 注意在 Settings->Secrets 配置 GITEE_PASSWORD
      #     gitee-password: ${{ secrets.GITEE_PASSWORD }}
      #     # 注意替换为你的 Gitee 仓库，仓库名严格区分大小写，请准确填写，否则会出错
      #     gitee-repo: freexll/tech_notes
      #     # 要部署的分支，默认是 master，若是其他分支，则需要指定（指定的分支必须存在）
      #     branch: master

ddd

配置pages

先 github部署脚本代码提交上去之后，会自动创建 gh-pages 分支
再在 GitHub 项目的Settings -> Pages路径下配置Build and deployment，source选 Deploy from a branch，branch选择gh-pages，路径选择/root，点击 save之后，找到 Your site 就能访问了。

参考资料

资料1

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

介绍 ​

创建项目 ​

部署到 Github Pages + Gitee Pages ​

配置ssh公私钥 ​

1.1 生成SSH公私钥: ​

1.2 添加私钥 ​

1.3 添加公钥 ​

创建github部署脚本 ​

配置pages ​

参考资料 ​