GitHub Pages 部署

本站使用 GitHub Actions 自动构建并发布到 GitHub Pages。推送到 main 分支后，站点在 1-2 分钟内自动更新。

首次部署流程

第一步：创建 GitHub 仓库

gh repo create your-username/your-repo --public --source . --remote origin --push

或者在 GitHub 网页创建仓库后：

git remote add origin https://github.com/your-username/your-repo.git
git push -u origin main

第二步：开启 GitHub Pages

1. 进入仓库 → Settings → Pages
2. Source 选择 Deploy from a branch
3. Branch 选择 gh-pages，目录选 / (root)
4. 点击 Save

gh-pages 分支何时出现

第一次推送到 main 后，GitHub Actions 会自动创建 gh-pages 分支。如果 Pages 设置里看不到这个分支，等 Actions 跑完再刷新。

第三步：确认 Actions 权限

进入仓库 → Settings → Actions → General → Workflow permissions，选择 Read and write permissions。

这是 mkdocs gh-deploy 写入 gh-pages 分支所必需的。

工作流说明

.github/workflows/deploy.yml 在每次推送到 main 时触发：

1. 拉取仓库代码
2. 安装 Python 和依赖（带缓存，通常 10 秒内完成）
3. 运行 mkdocs build --strict（构建失败则终止，不发布）
4. 运行 mkdocs gh-deploy --force 推送到 gh-pages 分支

自定义域名（可选）

如果你有自己的域名：

1. 在域名 DNS 添加 CNAME 记录，指向 your-username.github.io
2. 在仓库 Settings → Pages → Custom domain 填入域名
3. 在 docs/ 目录创建 CNAME 文件，内容为你的域名：

docs.yourdomain.com

1. 在 mkdocs.yml 更新 site_url：

site_url: https://docs.yourdomain.com/

常见问题

Actions 报错：Permission denied to github-actions[bot]

进入 Settings → Actions → General → Workflow permissions，改为 Read and write permissions。

站点 404

• 确认 Pages 设置里选的是 gh-pages 分支
• 确认 Actions 已经成功跑完（绿色勾）
• 等待 1-2 分钟让 CDN 刷新

mkdocs build --strict 失败

本地运行同样的命令查看具体错误：

mkdocs build --strict

常见原因：Markdown 语法错误、引用了不存在的文件、mkdocs.yml 配置有误。

样式丢失，只显示纯文本

mkdocs.yml 中的 site_url 必须与实际访问地址一致。如果用 GitHub Pages 默认域名，格式为：

site_url: https://your-username.github.io/your-repo/

注意末尾的斜杠不能省略。