折腾:使用 GitHub Codespaces + GitHub Pages 部署 Vitepress 文档

## 前言

作为一个热爱技术折腾的开发者,我总是喜欢尝试各种新奇的工具和框架。最近我发现了一个简洁、能够在 GitHub Pages 上部署的 VitePress 文档系统,决定用它来收集网络上的沙雕乐子。
一般人喜欢用自己电脑进行本地测试,这需要先在电脑上安装 Node.js 等环境,这还会有 Node.js 版本冲突、依赖安装失败、不同项目环境隔离等问题出现,或者没有电脑。
后来我发现了 GitHub Codespaces 于是就想能不能使用它来测试项目呢?于是试了一下,还真可以。

## 开始

正如标题所说,这是使用 GitHub 的工具部署的,所以需要一个 GitHub 账号,如果没有那就去注册一个。
当你有了 GitHub 账号,就需要准备一个空的仓库了,如果没有那就去创建一个,你可以在个人账户或者组织上创建,如果作为你或者你组织的主页就命名为 `<用户名/组织名>.github.io`。
然后就需要创建一个 Codespaces 了,打开仓库,点击 “Code” 按钮,然后点击 “Create Codespace on main” 这个很明显的按钮。
它将自动跳转至一个域名为 `<一堆字母和数字>.github.dev`,然后就能看到一个网页版的 VSCode。

## 安装与配置 VitePress

VSCode 下方有一个终端,直接输入 [官网教程](https://vitepress.dev/zh/guide/getting-started) 里的命令。

</s><i> </i>npm add -D vitepress<i> </i><e>
</s><i> </i>npx vitepress init<i> </i><e>

然后它就问了我几个简单的问题,大概就这样:

``` ┌ Welcome to VitePress! │ ◇ Where should VitePress initialize the config? │ ./docs │ ◇ Where should VitePress look for your markdown files? │ ./docs │ ◇ Site title: │ My Awesome Project │ ◇ Site description: │ A VitePress Site │ ◇ Theme: │ Default Theme │ ◇ Use TypeScript for config and theme files? │ Yes │ ◇ Add VitePress npm scripts to package.json? │ Yes │ ◇ Add a prefix for VitePress npm scripts? │ Yes │ ◇ Prefix for VitePress npm scripts: │ docs │ └ Done! Now run pnpm run docs:dev and start writing. ```

完成后它自动生成了几个文件夹和几个文件,打开 docs 里面的 .md 文件可以编辑和删除,用 Markdown 编写,也可以创建一些 .md 文件,例如 `googol.md`,`index.md` 是用于调整首页显示的内容的,注意**不要把 `index.md` 删了**,docs 文件夹内还有一个名为 .vitepress 的文件夹,这个文件夹是用于更改配置的,里面包含标题、描述、导航栏、侧边栏应该显示的内容。

## 部署至 GitHub Pages

配置完成后,在侧边栏找到 “源代码管理” 点进去,然后点击 “提交”,直接提交,返回 GitHub 仓库应该就能看到在 Codespaces 所做的更改已经应用到仓库中了。
然后就是用 workflows 部署至 GitHub Pages 了,在项目的 .github/workflows 目录中创建一个名为 deploy.yml 的文件,其中包含这样的内容:

``` name: Deploy VitePress site to Pages

on:
push:
branches: [main]

workflow_dispatch:

permissions:
contents: read
pages: write
id-token: write

concurrency:
group: pages
cancel-in-progress: false

jobs:

build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # 如果未启用 lastUpdated,则不需要
# - uses: pnpm/action-setup@v3 # 如果使用 pnpm,请取消此区域注释
# with:
# version: 9
# - uses: oven-sh/setup-bun@v1 # 如果使用 Bun,请取消注释
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm # 或 pnpm / yarn
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Install dependencies
run: npm ci # 或 pnpm install / yarn install / bun install
- name: Build with VitePress
run: npm run docs:build # 或 pnpm docs:build / yarn docs:build / bun run docs:build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: docs/.vitepress/dist

deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
needs: build
runs-on: ubuntu-latest
name: Deploy
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
```

接着在存储库设置中的“Pages”菜单项下,选择“Build and deployment > Source > GitHub Actions”。
等待一会应该就部署完成了,你应该能看到站点部署到 https://<用户名/组织名>.github.io/[仓库]/ 或 https://<自定义域名>/,这取决于你的设置。
进入站点看效果,这是我的站点 https://lezinote.github.io。

好干净整洁