All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading