/configure:github-pages

Check and configure GitHub Pages deployment.

When to Use This Skill

Use this skill when... Use another approach when...

Setting up GitHub Pages deployment for a documentation site Configuring documentation standards or generators (/configure:docs instead)

Creating or updating a GitHub Actions workflow for Pages deployment Debugging a failed GitHub Actions workflow (/configure:workflows instead)

Migrating from peaceiris/actions-gh-pages to official actions/deploy-pages

Editing documentation content or markdown files

Auditing Pages workflow for outdated action versions or missing permissions Setting up a custom domain via DNS (manual repository settings)

Adding Pages deployment to a project with an existing doc generator Configuring CI/CD workflows unrelated to documentation

Context

• GitHub workflows: !find .github/workflows -maxdepth 1 ( -name 'doc.yml' -o -name 'pages.yml' )

• Documentation config: !find . -maxdepth 1 ( -name 'mkdocs.yml' -o -name 'typedoc.json' -o -name 'docusaurus.config.*' )

• Docs directory: !find . -maxdepth 1 -type d ( -name 'docs' -o -name 'site' )

• CNAME file: !find . -maxdepth 1 -name 'CNAME'

• Project standards: !find . -maxdepth 1 -name '.project-standards.yaml'

Parameters

Parse from command arguments:

• --check-only : Report compliance status without modifications (CI/CD mode)

• --fix : Apply fixes automatically without prompting

• --source <docs|site|custom> : Override source directory detection

Execution

Execute this GitHub Pages deployment configuration check:

Step 1: Detect documentation state

Identify existing documentation configuration:

Config File Generator Output Directory

typedoc.json

TypeDoc docs/ or configured

mkdocs.yml

MkDocs site/

docs/conf.py

Sphinx docs/_build/html/

docusaurus.config.js

Docusaurus build/

Cargo.toml (with rustdoc) rustdoc target/doc/

None Static docs/

If no documentation configured, report:

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

Step 2: Analyze existing workflow

Check for existing GitHub Pages workflows by searching for:

• actions/deploy-pages

• actions/upload-pages-artifact

• peaceiris/actions-gh-pages

Extract from existing workflow: current action versions, permissions, build steps, source directory.

Step 3: Check compliance against standards

Validate GitHub Actions workflow against standards:

Check Standard Severity

actions/deploy-pages

v4+ WARN if older

actions/configure-pages

v5+ WARN if missing

actions/upload-pages-artifact

v3+ WARN if older

Permissions pages: write , id-token: write

FAIL if missing

Environment github-pages

WARN if missing

Concurrency Group defined INFO

Step 4: Generate compliance report

Print a formatted compliance report:

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 v4 [PASS | OUTDATED | MISSING] configure-pages v5 [PASS | MISSING] upload-artifact v3 [PASS | OUTDATED] Permissions pages: write, id-token [PASS | MISSING] Environment github-pages [PASS | MISSING]

Overall: [X issues found]

Recommendations: [List specific fixes needed]

If --check-only , stop here.

Step 5: Create or update workflow (if --fix or user confirms)

Create .github/workflows/docs.yml based on detected generator. Use the appropriate workflow template from REFERENCE.md:

• TypeDoc: Node.js setup, npm ci, npm run docs:build, upload ./docs

• MkDocs: Python setup, pip install, mkdocs build, upload ./site

• Sphinx: Python setup, pip install, make html, upload ./docs/_build/html

• rustdoc: Rust toolchain, cargo doc, create index redirect, upload ./target/doc

• Static HTML: Direct upload from ./docs directory

All workflows include:

• Required permissions (pages: write , id-token: write )

• Concurrency group to prevent conflicts

• workflow_dispatch for manual triggers

• Path-based triggers for relevant source files

Step 6: Update standards tracking

Update .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]"

Step 7: Print post-configuration instructions

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

For detailed workflow templates, see REFERENCE.md.

Output

Provide:

• Compliance report with documentation and workflow status

• List of changes made (if --fix) or proposed (if interactive)

• Post-configuration instructions

• URL where docs will be deployed

Agentic Optimizations

Context Command

Quick compliance check /configure:github-pages --check-only

Auto-fix all issues /configure:github-pages --fix

Check Pages workflow exists find .github/workflows -name 'pages' -o -name 'doc' 2>/dev/null

Check Pages action versions `grep -E 'deploy-pages

Verify Pages enabled gh api repos/{owner}/{repo}/pages --jq '.status'

Check deployment status gh api repos/{owner}/{repo}/pages/builds --jq '.[0].status'

See Also

• /configure:docs

• Set up documentation standards and generators

• /configure:workflows

• GitHub Actions workflow standards

• /configure:all

• Run all compliance checks

• /configure:status

• Quick compliance overview