Summary

The docs site currently deploys a single version. There is no way to view documentation for older releases, and the nav dropdown is not a real version selector — it just links to GitHub resources (Issues, Discussions, Releases).

This issue proposes switching to multi-version documentation so each release gets its own versioned docs deployment with a version switcher dropdown.

Approach: gh-pages branch

Switch from artifact-based deployment (actions/deploy-pages) to a gh-pages branch approach. This preserves previous versions across deployments because each deploy only adds/updates one directory in the branch.

Target directory structure:

gh-pages branch
├── index.html          # redirect to latest release
├── versions.json       # manifest of available versions
├── dev/                # built from push to main
├── v0.5.0/             # built after v0.5.0 release
├── v0.4.0/             # built after v0.4.0 release
└── ...

Implementation tasks

• Create orphan gh-pages branch with initial structure
• Reconfigure GitHub Pages to deploy from gh-pages branch instead of Actions artifacts
• Make VitePress base path dynamic — pass via env var (e.g., VITE_BASE_PATH) so each version builds with base: '/aether/v0.4.0/'
• Create version switcher component — custom Vue component in .vitepress/theme/ that fetches versions.json at runtime and renders a dropdown with links to each version
• Rewrite docs-deploy.yml workflow:
  • Checkout gh-pages branch
  • Build docs with correct base path for the target version
  • Copy built output to versioned directory (dev/ or vX.Y.Z/)
  • Update versions.json with new version entry
  • Update root index.html redirect to point to latest release
  • Commit and push to gh-pages
• Root redirect — index.html at root that redirects to the latest release version

Notes

• dev version is rebuilt on every push to main
• Release versions are built when CI completes for a tag push (using the workflow_run trigger from fix(docs): release event never triggers docs rebuild due to GITHUB_TOKEN limitation #191)