Setting up versioning¶
Material for MkDocs makes it easy to deploy multiple versions of your project documentation by integrating with external utilities that add those capabilities to MkDocs, i.e. mike. When deploying a new version, older versions of your documentation remain untouched.
mike makes it easy to deploy multiple versions of your project documentation. It integrates natively with Material for MkDocs and can be enabled via
This renders a version selector in the header:
mike is built around the idea that once you've generated your docs for a particular version, you should never need to touch that version again. This means you never have to worry about breaking changes in MkDocs, since your old docs (built with an old version of MkDocs) are already generated and sitting in your
While mike is flexible, it's optimized around putting your docs in a
<major>.<minor> directory, with optional aliases (e.g.
dev) to particularly notable versions. This makes it easy to make permalinks to whatever version of the documentation you want to direct people to.
8.0.0 · Customization
- Given this value for the
hrefattribute, the link will always redirect to the root of your site, which will then redirect to the latest version. This ensures that older versions of your site do not depend on a specific alias, e.g.
latest, to allow for changing the alias later on without breaking earlier versions.
This will render a version warning above the header:
The default version is identified by the
latest alias. If you wish to set another alias as the latest version, e.g.
stable, add the following lines to
Make sure that this matches the default version.
Stay on page¶
Insiders improves the user experience when switching between versions: if version A and B contain a page with the same path name, the user will stay on the current page:
While this section outlines the basic workflow for publishing new versions, it's best to check out mike's documentation to make yourself familar with its mechanics.
Publishing a new version¶
If you want to publish a new version of your project documentation, choose a version identifier and update the alias set as the default version with:
Note that every version will be deployed as a subdirectory of your
Setting a default version¶
When starting with mike, a good idea is to set an alias as a default version, e.g.
latest, and when publishing a new version, always update the alias to point to the latest version:
When publishing a new version, mike will create a redirect in the root of your project documentation to the version associated with the alias: