# Add Versioned Documentation to an MkDocs Site With mike

Yes. An agent adds mike to your MkDocs Material site, wires the version selector and release script, rehearses a deploy on a local gh-pages branch and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-versioned-docs/mkdocs/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the docs are built and published before it changes either. In a library like encode/httpx, `mkdocs.yml` uses the `material` theme with a `custom_dir` of `docs/overrides`, a `site_url` of `https://www.python-httpx.org/`, a five-section `nav`, and the `admonition`, `codehilite` and `mkautodoc` extensions. `requirements.txt` pins `mkdocs` 1.6.1, `mkdocs-material` 9.6.18 and `mkautodoc` 0.2.0 beside the test tooling. `scripts/build` runs `python -m build`, `twine check` and `mkdocs build`, and `scripts/publish`, which `.github/workflows/publish.yml` runs on every pushed tag after checking that the tag matches `__version__` in `httpx/__version__.py`, uploads to PyPI and then runs `mkdocs gh-deploy --force`. `docs/CNAME` holds `www.python-httpx.org`, and `docs/overrides/partials/nav.html` is the only template override. The test workflow runs `scripts/build` on every pull request, so the docs already build in CI. The current version is 0.28.1, every tag overwrites the whole site, and a reader on an older release has no way to read the docs that matched it.

Then it adds mike the way the theme documents. `mike` is pinned in `requirements.txt` under the documentation entries. `mkdocs.yml` gains `extra.version.provider: mike` so Material renders the version selector in the header, `extra.version.alias: true` so the selector shows `latest` beside the number, and a `plugins` list with `mike` and the `search` plugin, which must be named once any `plugins` key exists. Because the site already overrides templates from `docs/overrides`, the agent adds a `main.html` there that extends `base.html` and fills the `outdated` block with a one-line notice linking to the site root, so an old version tells the reader it is old without hard-coding which version is current.

The release script changes by one command. In `scripts/publish`, `mkdocs gh-deploy --force` becomes `mike deploy --push --update-aliases ${MAJOR_MINOR} latest`, where the major and minor come from the same `__version__` the script already reads for the tag check, so `0.28.1` publishes under `0.28` and moves `latest` to it. `mike set-default latest` is a one-time command run once after the first versioned deploy, and the agent puts it in the pull request as a step rather than in the script. The first deploy also needs a decision about the files already on `gh-pages`, which mike documents as deleting or moving before the first versioned deploy; the pull request spells that out instead of doing it, because the agent never pushes to the real branch.

It rehearses the deploy where it cannot do harm. In its sandbox the agent runs `mkdocs build` to confirm the config still builds with the plugin and the override, then runs `mike deploy 0.28 latest` without `--push`, which commits to a local `gh-pages` branch, and inspects it: a `0.28/` directory with the site, a `latest` alias, a `versions.json` listing `0.28` with its alias, and after `mike set-default latest`, a root `index.html` that redirects. `mike list` prints `0.28 [latest]`. It runs `scripts/check` for the linters, checks `git status` shows nothing from the rehearsal left behind on the working branch, and opens the pull request with the branch listing in it.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add versioned documentation with mike to this MkDocs Material site. Read mkdocs.yml, requirements.txt, scripts/build, scripts/publish, .github/workflows/publish.yml, .github/workflows/test-suite.yml, docs/CNAME and the templates under docs/overrides first. Pin mike in requirements.txt beside the other documentation tools. In mkdocs.yml set extra.version.provider to mike and extra.version.alias to true, and add a plugins list with search and mike. Add docs/overrides/main.html extending base.html with an outdated block that links to the site root. In scripts/publish replace mkdocs gh-deploy --force with mike deploy --push --update-aliases using the major and minor of the version the script already reads, and latest as the alias. Rehearse in the sandbox without pushing: run mkdocs build, then mike deploy for the current major.minor with the latest alias, then mike set-default latest, and record the gh-pages branch listing, versions.json and mike list output. Run scripts/check. Do not push any branch yourself and do not delete anything on gh-pages. Open a pull request that quotes the rehearsal output and lists the one-time first-deploy steps, including what to do with the files already on gh-pages.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that changes `requirements.txt`, `mkdocs.yml` and `scripts/publish`, and adds `docs/overrides/main.html`. The description quotes the rehearsal: the `0.28/` directory and `latest` alias on the local `gh-pages` branch, the `versions.json` contents, the `mike list` line, and the redirecting root page after `set-default`. A numbered section lists the one-time steps for the first real deploy: what to do with the existing files on `gh-pages`, running `mike set-default --push latest` once, and confirming `www.python-httpx.org` still resolves to the site afterwards.

The run's record keeps the `mkdocs build` output with the plugin loaded, every `mike` command and its result, the branch inspection and the `scripts/check` output, and shows that no push happened.

Before merging, a reviewer decides whether older releases should be back-filled as versions by checking out their tags and running `mike deploy` for each, which the pull request describes but does not do, and confirms the next tag push is the right moment for the first versioned deploy.

## Run it on every library with an MkDocs site

An organisation with several libraries publishing MkDocs sites sends this body once per repository to `POST /o/{org}/sessions`, each with its repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started rather than a second pull request. Each run reads its own publish script and theme, so a site that deploys from a workflow step rather than a script, or has no override directory yet, gets the matching change.

After the change is merged, no run is needed per release: the existing tag-triggered publish deploys each version through `mike`. A `webhook_url` on the key reports each setup run as `run.completed` with the pull request in `result`, and a `run.failed` names a site whose build broke with the plugin.

## Why run it on Rush?

The risky part of versioning docs is the first deploy, which rewrites a branch that serves a public domain. The agent rehearses that deploy on a local `gh-pages` branch in its own sandbox, reads the resulting tree and `versions.json`, and never pushes, so the pull request shows what the real deploy will produce before anyone runs it.

The rehearsal output stays with the run and goes into the pull request, so the reviewer's decisions, how to treat the old files and whether to back-fill releases, are made with the exact commands and their results in front of them.

## Frequently asked questions

### Will the existing site go down during the switch?

Not from this pull request, which pushes nothing. The first real `mike deploy` writes a `0.28/` directory and aliases next to whatever is on `gh-pages`, and `set-default latest` adds a redirecting root page; the pull request lists these steps in order so the cut-over is one deliberate deploy.

### Does the custom domain keep working?

`docs/CNAME` is part of the MkDocs source, so it is built into each version's output. The pull request's first-deploy checklist includes confirming the domain after the deploy, because the root of the branch is what GitHub Pages reads it from.

### Can older releases get their own versions later?

Yes. Checking out a release tag and running `mike deploy <major.minor>` publishes that release's docs beside the current one without touching it; the pull request describes the loop and leaves the choice of how far back to go to the maintainers.

### Why change scripts/publish instead of the workflow?

Because `publish.yml` only calls `scripts/publish`, and that script already reads `__version__` to check the tag. Deriving the mike version from the same value keeps one source of truth, and the test workflow's `scripts/build` step keeps checking that the site builds with the plugin on every pull request.

## More MkDocs jobs

- [Migrate MkDocs API Docs From mkautodoc to mkdocstrings](https://getrush.ai/run/migrate-to-mkdocstrings/mkdocs/)
- [Add a Workflow That Deploys MkDocs Documentation on Every Push](https://getrush.ai/run/add-deploy-workflow/mkdocs/)
- [Add a Strict Docs Build Check to MkDocs Docs](https://getrush.ai/run/add-docs-build-check/mkdocs/)

## The same job on other stacks

- [Add Versioned Docs to a Starlight Site](https://getrush.ai/run/add-versioned-docs/starlight/)
- [Add Versioned Docs to a VitePress Site](https://getrush.ai/run/add-versioned-docs/vitepress/)
- [Add Versioned Docs to a Docusaurus Site](https://getrush.ai/run/add-versioned-docs/docusaurus/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
