Automate docs site deployment to GitHub Pages via GitHub Actions

[vinodmut]

Problem

The documentation site at https://agenttoolkit.github.io/altk-evolve/ is not deployed automatically. Today it only updates when someone runs mkdocs gh-deploy by hand from a local machine.

Concretely:

• GitHub Pages is configured as legacy build, serving the gh-pages branch (source: gh-pages, path: /).
• The gh-pages branch was last updated 2026-04-10 (e0601b77) and has only ever been updated manually.
• No workflow in .github/workflows/ builds or deploys the docs — check-code, check-vulnerabilities, docker-publish, python-publish, and release-github contain no mkdocs/Pages steps.

Impact: docs changes merged to main do not go live until a maintainer remembers to deploy. For example, #290 merged a fix but the change is not visible on the site because gh-pages was never rebuilt.

Proposal

Add a GitHub Actions workflow that builds the mkdocs site and publishes it automatically on merge to main, plus a manual trigger.

Option A (recommended): Pages via Actions artifact

Switch the Pages source from "Deploy from a branch (gh-pages)" to "GitHub Actions" (Settings → Pages, one-time, requires repo admin), then add .github/workflows/docs.yaml:

name: Deploy docs
on:
  push:
    branches: [main]
    paths: ['docs/**', 'mkdocs.yaml', 'pyproject.toml', '.github/workflows/docs.yaml']
  workflow_dispatch:

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

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

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv sync
      - run: uv run mkdocs build -f mkdocs.yaml -d site
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: site
      - id: deploy
        uses: actions/deploy-pages@v4

Pros: no force-pushes, no gh-pages branch to maintain, native deployment history/environment, least surprising going forward.
Cons: requires the one-time Pages-source switch to "GitHub Actions".

Option B: keep gh-pages, automate gh-deploy

If we want to keep the current legacy/gh-pages setup unchanged, run mkdocs gh-deploy in CI instead:

name: Deploy docs
on:
  push:
    branches: [main]
    paths: ['docs/**', 'mkdocs.yaml', 'pyproject.toml', '.github/workflows/docs.yaml']
  workflow_dispatch:
permissions:
  contents: write   # needed to push gh-pages
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: astral-sh/setup-uv@v5
      - run: uv sync
      - run: uv run mkdocs gh-deploy -f mkdocs.yaml --force

Pros: zero Settings changes; keeps gh-pages as-is.
Cons: force-pushes gh-pages on every deploy; contents: write is broader than Option A's scoped pages: write.

Recommendation

Go with Option A — it's the current GitHub-recommended path, avoids force-pushing, and gives proper deployment tracking. The only cost is the one-time Pages-source switch.

Notes / open questions

• The paths filter limits deploys to docs-affecting changes; drop it if we prefer to redeploy on every merge to main.
• mkdocs.yaml currently has site_url: https://agenttoolkit.github.io/evolve while the site is served at /altk-evolve/ — worth correcting alongside this (minor, pre-existing).
• Confirm the intended deploy process with maintainers (see discussion on fix(docs): point repo card Stars link to repo home #290) before switching approaches.

[vinodmut]

@illeatmyhat what do you think of this? Option A (Pages via Actions) vs Option B (automate mkdocs gh-deploy on the existing gh-pages branch) — do you have a preference, or is there an existing deploy convention I should follow instead?

[illeatmyhat]

The site_url is intentional. It's built this way because https://altk.ai is actually three projects in one.
We should go for option B. The "benefits" proposed for option A actually don't make any sense at all because gh-pages is just a blank branch that does nothing but host artifacts. We really don't care about the history.