{"id":4109,"library":"mike","title":"mike","description":"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.","status":"active","version":"2.1.4","language":"en","source_language":"en","source_url":"https://github.com/jimporter/mike","tags":["documentation","mkdocs","versioning","static-site","git","github-pages"],"install":[{"cmd":"pip install mike","lang":"bash","label":"Install mike"}],"dependencies":[{"reason":"mike manages versions of MkDocs documentation, so MkDocs itself is a fundamental prerequisite.","package":"mkdocs","optional":false},{"reason":"mike interacts directly with Git for deploying documentation versions to branches like `gh-pages`.","package":"git","optional":false}],"imports":[{"note":"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.","symbol":"mike","correct":"plugins:\n  - mike"}],"quickstart":{"code":"mkdocs new my-docs\ncd my-docs\n# Add some content or configure mkdocs.yml\necho 'theme: readthedocs' >> mkdocs.yml\n\n# Deploy the initial version and an alias\nmike deploy 1.0 latest\n\n# Set the default version to 'latest'\nmike set-default latest\n\n# Serve the documentation locally (includes version selector)\nmike serve\n\n# To add another version later:\nmike deploy 2.0\n\n# To update an existing alias:\nmike alias 2.0 stable --update-aliases\n\n# To list deployed versions:\nmike list","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<2.0.0"},{"fix":"Upgrade to `mike>=2.1.0` to ensure proper execution of MkDocs' `startup` and `shutdown` events.","message":"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.","severity":"gotcha","affected_versions":"<2.1.0"},{"fix":"Ensure `mike>=2.1.1` is installed if you are using `INHERIT` directives with environment variables in your `mkdocs.yml` file.","message":"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.","severity":"gotcha","affected_versions":"<2.1.1"},{"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`.","message":"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).","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}