On this page

Versioned Docs

Keep the docs of older releases online, with a menu to switch between versions.

MkDocs builds one version of your docs at a time. To publish several, use mike: it builds each version into a folder of its own, such as 1.0/ and 2.0/, on the gh-pages branch, and writes a versions.json file that lists them for the version menu.

gh-pages branch
    1.0/
    2.0/
    latest -> 2.0
    index.html        # redirects to the default version
    versions.json

Setting up mike

Install mike next to MkDocs NG:

pip install mkdocs-ng mike

mike installs the upstream mkdocs package too, as plugins do. MkDocs NG takes precedence, see Updating your dependencies.

mike builds with MkDocs NG even when a plugin, such as mkdocs-redirects, has installed ProperDocs too.

Add the mike plugin to mkdocs.yml, and turn on the version menu of your theme.

MkDocs and ReadTheDocs themes

mike adds its version menu to the built-in mkdocs and readthedocs themes:

plugins:
  - search
  - mike

Sumi

Sumi shows a version menu in the header, and a notice on the pages of older versions. See Sumi's navigation docs.

theme:
  name: sumi
  version_provider: mike
plugins:
  - search
  - sumi
  - mike

Material for MkDocs

plugins:
  - search
  - mike
extra:
  version:
    provider: mike

See Material's versioning docs for the other options, such as the notice on older versions.

Publishing a version

Deploy each release with its version and, for the newest one, an alias such as latest:

mike deploy --push --update-aliases 1.0 latest

Then make latest the version that the root of the site opens, once:

mike set-default --push latest

For the next release, deploy 1.1 with the latest alias: the alias moves from 1.0 to 1.1, and the root of the site follows it.

Use the version without the patch number, 1.1 rather than 1.1.3, so that patch releases update their minor version in place instead of adding an entry to the menu for every release.

Other useful commands:

mike list lists the deployed versions and their aliases.
mike serve serves the gh-pages branch at http://localhost:8000/, to check the version menu before pushing. Keep using mkdocs serve while you write: it shows the version you are working on, without the menu.
mike delete --push 0.9 removes an old version.
mike retitle --push 1.0 "1.0 (LTS)" changes the title shown in the menu.

Without --push, mike only commits to your local gh-pages branch.

Publishing from GitHub Actions

This workflow deploys the development docs as dev on every push to main, and each release tag such as v1.2.3 as 1.2 with the latest alias:

name: docs
on:
  push:
    branches: [main]
    tags: ["v*"]
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0  # mike adds a commit to the existing gh-pages branch
      - uses: actions/setup-python@v7
        with:
          python-version: "3.x"
      - run: pip install mkdocs-ng mike
      - run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
      - if: github.ref_type == 'branch'
        run: mike deploy --push dev
      - if: github.ref_type == 'tag'
        run: |
          version="${GITHUB_REF_NAME#v}"
          mike deploy --push --update-aliases "${version%.*}" latest

In the repository's settings, under Pages, publish from the gh-pages branch.

URLs

mike adds the version to site_url, so the canonical URLs, the sitemap and llms.txt of each version point to its own folder, such as https://example.com/1.0/guide/.

To have search engines index only the newest docs, point the canonical URLs of every version to the latest alias:

plugins:
  - mike:
      canonical_version: latest

With a custom domain, keep the CNAME file at the root of the gh-pages branch, where GitHub writes it when you set the domain in the repository's settings, rather than in docs_dir: mike leaves files outside the version folders alone.

mike makes an alias a symbolic link to its version. GitHub Pages follows it. If your host doesn't, set alias_type: redirect, which writes pages that redirect to the version instead, or alias_type: copy.

Multi-language sites

On a multi-language site, each version holds every language: 1.0/ for the default language and 1.0/zh/ for Chinese. Deploy it the same way.

Changed in version 1.11.2

Earlier versions put the language before the version in the canonical URLs, the sitemap and the links between languages: /zh/1.0/ instead of /1.0/zh/.

For now, the version menu of mike, Sumi and Material shows on the pages of the default language only.