Skip to content

Documentation Versioning

The documentation site supports versioning using the mike tool, which manages versions on the gh-pages branch.

Quick Start

  • Deploy a stable release (e.g., 1.0) and set as latest/default:

    ./scripts/docs-version.sh 1.0

  • Deploy a development (nightly) version:

    ./scripts/docs-version.sh dev dev

  • List versions locally:

    mike list

CI/CD

The workflow .github/workflows/docs.yml automatically deploys versioned docs: - Tag push vX.Y.Z → deploys version X.Y.Z, updates latest, and sets it as default - Push to main → deploys dev version with dev alias

Note: Configure GitHub Pages to serve from the gh-pages branch in repository settings (Pages → Build and deployment → Source → Deploy from a branch).

mkdocs.yml

Versioning is enabled in MkDocs via:

extra:
  version:
    provider: mike
    default: latest

This activates the version selector in the Material theme.

Tips

  • Use semantic versions for tags: v1.0.0
  • Keep latest pointing to the newest stable release
  • Use dev for rolling documentation on the main branch

  • Clean up old versions if needed:

    mike delete 0.9 --push

Troubleshooting

  • Version selector missing: Ensure Material theme is used and extra.version.provider: mike is set
  • “gh-pages” not updating: Confirm CI has contents: write permission and pushes succeed
  • Wrong site source: Switch repository Pages source to “Deploy from a branch” using gh-pages