configure-github-pages

/configure:github-pages

检查并配置 GitHub Pages 部署。

何时使用此技能

在以下情况下使用此技能……	在以下情况下采用其他方法……
为文档网站设置 GitHub Pages 部署	配置文档规范或生成器（改用 /configure:docs）
创建或更新用于 Pages 部署的 GitHub Actions 工作流	调试失败的 GitHub Actions 工作流（改用 /configure:workflows）
从 peaceiris/actions-gh-pages 迁移到官方的 actions/deploy-pages	编辑文档内容或 markdown 文件
审核 Pages 工作流，检查是否存在过时的操作版本或缺少权限	通过 DNS 设置自定义域名（在仓库设置中手动配置）
为已有文档生成器的项目添加 Pages 部署	配置与文档无关的 CI/CD 工作流

上下文

• GitHub 工作流： !find .github/workflows -maxdepth 1 \( -name '*doc*.yml' -o -name '*pages*.yml' \)
• 文档配置： !find . -maxdepth 1 \( -name 'mkdocs.yml' -o -name 'typedoc.json' -o -name 'docusaurus.config.*' \)
• 文档目录： !find . -maxdepth 1 -type d \( -name 'docs' -o -name 'site' \)
• CNAME 文件： !find . -maxdepth 1 -name 'CNAME'
• 项目规范： !find . -maxdepth 1 -name '.project-standards.yaml'

参数

从命令参数中解析：

• --check-only：仅报告合规状态，不进行修改（CI/CD 模式）
• --fix：自动应用修复，不提示确认
• --source <docs|site|custom>：覆盖源目录检测结果

执行

执行此 GitHub Pages 部署配置检查：

步骤 1：检测文档状态

识别现有文档配置：

配置文件	生成器	输出目录
typedoc.json	TypeDoc	docs/ 或已配置的目录
mkdocs.yml	MkDocs	site/
docs/conf.py	Sphinx	docs/_build/html/
docusaurus.config.js	Docusaurus	build/
Cargo.toml（含 rustdoc）	rustdoc	target/doc/
无	静态	docs/

如果未配置文档，则报告：

No documentation generator detected.

Consider running /configure:docs first to:
  - Set up documentation linting standards
  - Configure a documentation generator

Would you like to:
  [A] Configure documentation first (/configure:docs)
  [B] Set up static HTML hosting for existing docs/ directory
  [C] Skip - I'll configure docs later

步骤 2：分析现有工作流

通过搜索以下内容检查是否已有 GitHub Pages 工作流：

• actions/deploy-pages
• actions/upload-pages-artifact
• peaceiris/actions-gh-pages

从现有工作流中提取：当前操作版本、权限、构建步骤、源目录。

步骤 3：根据规范检查合规性

根据规范验证 GitHub Actions 工作流：

检查项	规范	严重级别
actions/deploy-pages	v5+	版本较旧时警告
actions/configure-pages	v6+	缺失时警告
actions/upload-pages-artifact	v5+	版本较旧时警告
权限	pages: write、id-token: write	缺失时失败
环境	github-pages	缺失时警告
并发	已定义组	信息

步骤 4：生成合规报告

打印格式化的合规报告：

GitHub Pages Compliance Report
==============================
Project: [name]

Documentation Status:
  Generator           [typedoc|mkdocs|sphinx|rustdoc|static|not configured]
  Source directory    [docs/|site/|custom]
  Build command       [detected command or "not configured"]

GitHub Pages Workflow:
  Workflow file       .github/workflows/docs.yml    [EXISTS | MISSING]

Workflow Checks (if exists):
  deploy-pages        v5                            [PASS | OUTDATED | MISSING]
  configure-pages     v6                            [PASS | MISSING]
  upload-artifact     v5                            [PASS | OUTDATED]
  Permissions         pages: write, id-token        [PASS | MISSING]
  Environment         github-pages                  [PASS | MISSING]

Overall: [X issues found]

Recommendations:
  [List specific fixes needed]

如果指定了 --check-only，则在此处停止。

步骤 5：创建或更新工作流（如果指定了 --fix 或用户确认）

根据检测到的生成器创建 .github/workflows/docs.yml。使用 REFERENCE.md 中相应的工作流模板：

• TypeDoc：设置 Node.js、运行 npm ci、运行 npm run docs:build、上传 ./docs
• MkDocs：设置 Python、安装 pip、运行 mkdocs build、上传 ./site
• Sphinx：设置 Python、安装 pip、运行 make html、上传 ./docs/_build/html
• rustdoc：设置 Rust 工具链、运行 cargo doc、创建索引重定向、上传 ./target/doc
• 静态 HTML：直接从 ./docs 目录上传

所有工作流均包含：

• 所需权限（pages: write、id-token: write）
• 用于防止冲突的并发组
• 用于手动触发的 workflow_dispatch
• 针对相关源文件的路径触发器

步骤 6：更新规范跟踪

更新 .project-standards.yaml：

standards_version: "2025.1"
last_configured: "[timestamp]"
components:
  github-pages: "2025.1"
  github-pages-generator: "[typedoc|mkdocs|sphinx|rustdoc|static]"
  github-pages-source: "[docs/|site/|custom]"

步骤 7：打印配置后说明

GitHub Pages Configuration Complete
===================================

Workflow created: .github/workflows/docs.yml

Next Steps:
  1. Enable GitHub Pages in repository settings:
     Settings -> Pages -> Source: GitHub Actions

  2. Push to main branch to trigger deployment:
     git add .github/workflows/docs.yml
     git commit -m "ci(docs): add GitHub Pages deployment workflow"
     git push

  3. After deployment, your docs will be available at:
     https://OWNER.github.io/REPO/

Optional:
  - Add custom domain: Create CNAME file with your domain
  - Protect deployment: Configure environment protection rules

如需详细的工作流模板，请参阅 REFERENCE.md。

输出

提供：

1. 包含文档和工作流状态的合规性报告
2. 已进行的更改（如果使用 --fix）或拟议的更改（如果采用交互模式）
3. 配置后说明
4. 文档将部署到的网址

Agent 优化

场景	命令
快速合规性检查	/configure:github-pages --check-only
自动修复所有问题	/configure:github-pages --fix
检查 Pages 工作流是否存在	find .github/workflows -name '*pages*' -o -name '*doc*' 2>/dev/null
检查 Pages 操作版本	`grep -E 'deploy-pages
验证 Pages 是否已启用	gh api repos/{owner}/{repo}/pages --jq '.status'
检查部署状态	gh api repos/{owner}/{repo}/pages/builds --jq '.[0].status'

另请参阅

• /configure:docs - 设置文档规范和生成器
• /configure:workflows - GitHub Actions 工作流规范
• /configure:all - 运行所有合规性检查
• /configure:status - 快速查看合规性概况