GitHub Pages

Deploy `docs/` as static site

On push to `main` or `master`, the workflow uploads `docs` and deploys to GitHub Pages.

Summary

1. Commit `.github/workflows/docs-pages.yml`.

2. Set Pages Source to GitHub Actions.

3. Ensure `Release Gate` workflow passes before publish.

4. Push and verify workflow success.

5. Open deployed URL.

Workflow file

name: Deploy Docs to GitHub Pages

on:
  push:
    branches: ["main", "master"]
    paths:
      - "docs/**"
      - ".github/workflows/docs-pages.yml"
  workflow_dispatch:

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

concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs
      - id: deployment
        uses: actions/deploy-pages@v4

Repository settings

Open Settings in your repository.
Go to Pages.
Set Source to GitHub Actions.
Check the latest deployment in Actions.

Release gate workflow: .github/workflows/release-gate.yml
Local equivalent: npm run release:gate

Local preview

cd docs
python3 -m http.server 4173
# http://localhost:4173

Troubleshooting

Issue	Fix
404 on refresh	Use static `.html` links for each page (no SPA rewrite needed).
Styles not loaded	Verify path to `../assets/site.css` in language pages.
Old page still shown	Clear browser cache and verify latest Pages deployment artifact.