GitHub Pages 部署说明

本页是 docs/site-configs/github-pages-workflow.yml.example 的配套说明。 如果你准备把当前 VitePress 文档站部署到 GitHub Pages，建议先按下面的顺序检查。

0. 通过网页访问：完整配置步骤

第一步：在仓库里启用 GitHub Pages

1. 打开你的仓库页面，例如：https://github.com/RosyDawns/ai-agent-guide
2. 点击顶部 Settings（设置）
3. 左侧菜单找到 Pages
4. 在 Build and deployment 下：
   • Source 选择 GitHub Actions
   • 不要选 “Deploy from a branch”（本项目用 Actions 部署）
5. 保存后无需再点其他按钮，部署由 push 到 main 或手动运行 workflow 触发。

第二步：确认部署是否成功

1. 点击仓库顶部 Actions
2. 找到 Deploy Docs workflow，查看最近一次运行是否绿色 ✓
3. 若失败，点进去看具体报错；若成功，继续下一步。

第三步：记住访问地址

• 项目仓库（仓库名不是 你的用户名.github.io）
  站点地址为：
  https://你的用户名.github.io/ai-agent-guide/
  例如：https://RosyDawns.github.io/ai-agent-guide/

• 个人主页仓库（仓库名为 你的用户名.github.io）
  站点地址为：
  https://你的用户名.github.io/

本项目是“项目仓库”，因此首页路径带 /ai-agent-guide/。VitePress 的 base 已在 workflow 里自动设为 /$REPO_NAME/，无需改代码。

第四步：首次或修改后发布

• 自动：往 main 分支 push 代码后，GitHub Actions 会自动构建并部署。
• 手动：打开 Actions → 选 Deploy Docs → Run workflow → Run workflow，跑完即可刷新站点。

---

1. 仓库设置

• 确保默认分支为 main，或在 workflow 中改成你自己的分支名。
• 在仓库的 Pages 设置里启用 GitHub Pages。
• 如果仓库是项目仓库而不是用户主页仓库，后续还需要检查 base / 站点路径设置。

2. CI 流程

当前示例 workflow 做了 4 件事：

1. 检出仓库
2. 安装 Node.js 和依赖
3. 执行 npm run docs:build
4. 把 docs/.vitepress/dist/ 发布到 GitHub Pages

3. 什么时候要改配置

你可能需要修改这些内容：

• push.branches：如果默认分支不是 main
• node-version：如果你想锁定不同 Node 版本
• path：如果你调整了 VitePress 输出目录
• base：如果你的 GitHub Pages 是项目路径而不是根路径

4. 推荐做法

• 在正式启用前，先本地执行一次 npm run docs:build
• 先用 workflow_dispatch 手动触发一次，确认 Pages 产物正确
• 首页路径如果异常，优先检查 VitePress 的 base 配置