mike

2.1.4 · active · verified Sat Apr 11

mike is a Python utility designed to simplify the deployment of multiple versions of your MkDocs-powered documentation to a Git branch, commonly `gh-pages`. This approach allows you to archive older documentation versions, ensuring they remain accessible even if future MkDocs updates introduce breaking changes. The current version is 2.1.4, with a release cadence that includes frequent bug fixes and less frequent but consistent minor/major feature releases.

Warnings

breaking In `mike` v2.0.0, the default behavior for deploying aliases changed from copying files (`copy`) to using symbolic links (`symlink`). Additionally, empty commits are no longer created by default during deployment.
Fix: If relying on the old behavior, explicitly specify `--alias-type copy` in CLI commands or `alias_type: copy` in the `mike` plugin configuration in `mkdocs.yml`. To allow empty commits, add `--allow-empty` to `mike deploy` commands.
gotcha Prior to `mike` v2.1.0, when `mike` loaded the MkDocs configuration, it did not properly trigger the `startup` and `shutdown` events. This could lead to unexpected behavior or failures for other MkDocs plugins that rely on these events.
Fix: Upgrade to `mike>=2.1.0` to ensure proper execution of MkDocs' `startup` and `shutdown` events.
gotcha Full support for resolving `INHERIT` directives in `mkdocs.yml` when using environment variables (e.g., `!ENV [VAR, 'default']`) was only robustly added and fixed in `mike` v2.1.1. Older versions might not correctly parse or apply these variables, leading to configuration errors.
Fix: Ensure `mike>=2.1.1` is installed if you are using `INHERIT` directives with environment variables in your `mkdocs.yml` file.
gotcha When using `mike serve`, it only serves the *current* version of your documentation from your local files, not necessarily the versions committed to your `gh-pages` branch. For testing committed versions, use `mike serve` (which serves from the deployed branch) rather than `mkdocs serve` (which serves from local source).
Fix: Be mindful of which command you use for local testing: `mkdocs serve` for local source changes, `mike serve` for deployed (Git) branch content. For live sites, use a proper web server, not `mike serve` or `mkdocs serve`.

Install

pip install mike Install mike

Imports

mike
```
plugins:
  - mike
```
mike is primarily a CLI tool and an MkDocs plugin. Direct Python programmatic imports of its core functionality are less common for typical usage. Its primary 'import' is via the MkDocs configuration file (`mkdocs.yml`) to enable the versioning features and UI selector.

Quickstart

This quickstart demonstrates the core `mike` commands for setting up, deploying, and serving versioned MkDocs documentation. It includes creating a new MkDocs project, deploying initial versions with aliases, setting a default version, and viewing the documentation locally.

mkdocs new my-docs
cd my-docs
# Add some content or configure mkdocs.yml
echo 'theme: readthedocs' >> mkdocs.yml

# Deploy the initial version and an alias
mike deploy 1.0 latest

# Set the default version to 'latest'
mike set-default latest

# Serve the documentation locally (includes version selector)
mike serve

# To add another version later:
mike deploy 2.0

# To update an existing alias:
mike alias 2.0 stable --update-aliases

# To list deployed versions:
mike list

view raw JSON →