mike keeps every built version of your MkDocs site on one branch

The idea is that generated docs are never rebuilt

mike is a Python utility that makes it easy to deploy multiple versions of your MkDocs powered docs to a Git branch, suitable for hosting on GitHub via gh-pages. The rationale is stated more precisely than most tool descriptions, and it is the reason to reach for this rather than a custom script. The idea is that once you have generated your docs for a particular version, you should never need to touch that version again, which means you never have to worry about breaking changes in MkDocs, because your old docs, built with an old version of MkDocs, are already generated and sitting in your gh-pages branch. That is a different guarantee from the one a rebuild-based approach gives, and it is the guarantee that matters for an archive of released documentation. The README points at the bfg9000 documentation as an example of the workflow in action.

Every deploy is a commit, and only one version is touched

The mechanism is deliberately dull. mike works by creating a new Git commit on your gh-pages branch every time you deploy a new version of your docs, using mike deploy or other mike subcommands that change the branch. When deploying a particular version, previously deployed docs for that version are erased and overwritten, and docs for other versions remain untouched. The layout is optimised around a major.minor directory with optional aliases, such as latest or dev, for particularly notable versions, and the stated benefit is that it is easy to make permalinks to whatever version of the documentation you want to direct people to. The version string is whatever you like, though the README recommends major.minor and excluding the patch number, and the version is usually the current version of your project.

Aliases come in three flavours, and the choice has consequences

An alias is a second name for a version, and the three mechanisms behave differently on a static host. By default each alias creates a symbolic link to the base directory of the real version of the docs, and you can pass --alias-type=copy to copy the files instead, or --alias-type=redirect to use a simple HTML redirect for each page. The alias type can also be set in the plugin configuration as plugins.mike.alias_type, and the same is true of the branch and remote options, which map onto the built-in MkDocs fields remote_branch and remote_name. If you use redirects you can customise the template with the -T and --template options, which takes a path to a Jinja template accepting an href variable. There is also -t and --title=TITLE to set a title for a version that does not match the version string, and a set of property commands, --prop-set, --prop-set-string, --prop-set-all, --prop-delete and --prop-delete-all, for custom per-version values.

The MkDocs plugin is where the version selector comes from

mike integrates with the MkDocs build as a plugin, added by default when you build with mike, and adding it explicitly to your mkdocs.yml lets you configure how it behaves. The plugin adds a version selector to supported themes and updates the site_url, if you set one, to point at the version being built.

plugins:
  - mike:
      # These fields are all optional; the defaults are as below...
      alias_type: symlink
      redirect_template: null
      deploy_prefix: ''
      canonical_version: null
      version_selector: true
      css_dir: css
      javascript_dir: js

The options are alias_type, which takes symlink, redirect or copy, redirect_template for the HTML redirect template where null means the default, deploy_prefix as the root directory for the generated docs so that other pages can live at the site root or several independently versioned doc sets can sit side by side, canonical_version for telling search engines which pages to prefer, such as latest when that alias always points at the newest release, version_selector to toggle the selector, and css_dir and javascript_dir for where the selector's assets go. The package registers the plugin as an entry point named mike under mkdocs.plugins, and it ships theme entry points for MkDocs, Read the Docs, and a long list of Bootswatch themes, including bootstrap, cerulean, cosmo, cyborg, darkly, flatly, journal, litera, lumen, lux, materia and minty.

Deploying, pushing and the first-run cleanup

The deploy command takes an optional version and any number of aliases, so a full invocation is mike deploy followed by the version and then the aliases. If the version already exists, the command also updates all the pre-existing aliases for it, and normally an alias that is already associated with another version is an error, unless you pass -u or --update-aliases, which is what you want when releasing a new version and moving latest onto it. Where the docs go is controlled by -b or --branch, -r or --remote and --deploy-prefix, and adding -p or --push pushes the docs to the remote branch. Before using mike for the first time, the README suggests running mike delete --all to remove any old documentation on the gh-pages branch, or alternatively moving that documentation into a subdirectory by hand so it stays accessible. During editing, the ordinary mkdocs serve is enough to preview the work.

Where mike is the wrong shape of tool

Three limits are worth naming. The first is that mike assumes a versioning scheme that matches your releases, and it optimises around major.minor directories, so a project with a single moving version of its docs gains very little and inherits a directory layout it did not ask for. The second is that the symlink default is a real constraint on the hosting side, because a symbolic link committed to a branch is only resolved by a server that checks them out properly, and the readme offers copy and redirect as the alternatives for hosts that do not. The third is that the tool is a build and deploy utility rather than a documentation system, so it does not solve search, navigation or authoring, and the readme itself points at plain mkdocs serve for the editing loop. What it does solve, which is keeping a released version of the documentation permanently buildable, is a small enough job that a determined team could also write, and mike is the well-tested version of that script rather than a platform to build on.

Editorial conclusion

mike suits a project that publishes documentation for several released versions and wants the old builds to keep working without rebuilding them, and it suits anyone who wants a versioned docs site on GitHub Pages without running a documentation server. It is the wrong tool for a single-version documentation set, where a plain MkDocs build and a branch push is enough, and it is the wrong tool if your documentation lives outside Git, since the whole model is a commit per version on a branch. Before adopting it, decide whether your aliases should be symlinks, redirects or copies, because the three behave differently on a static host and on GitHub Pages, and note that a symlink alias is a real symbolic link in the repository. The last push was on 2026-10-14 and the current release is v2.2.0 from 2026-04-14.

Frequently asked questions

Official sources

1. Issues
2. jimporter/mike on GitHub
3. License: BSD-3-Clause
4. README
5. Releases