3.2 KiB
| template |
|---|
| overrides/main.html |
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.
Configuration
Versioning
:octicons-file-code-24: Source · :octicons-package-24: Utility · :octicons-beaker-24: Experimental ·
mike makes it easy to deploy multiple versions of your project
documentation. It integrates natively with Material for MkDocs and can be
enabled via mkdocs.yml:
extra:
version:
provider: mike
This will render a version selector in the header next to the title of your project:
A demo is worth a thousand words — check it out at squidfunk.github.io/mkdocs-material-example-versioning
!!! quote "Why use mike?"
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 `gh-pages` branch.
While mike is flexible, it's optimized around putting your docs in a
`<major>.<minor>` directory, with optional aliases (e.g. `latest` or `dev`)
to particularly notable versions. This makes it easy to make permalinks to
whatever version of the documentation you want to direct people to.
Note that you don't need to run mike install-extras as noted in the
official documentation, as mike is now natively integrated with
Material for MkDocs.
Usage
While this section outlines the basic workflow for publishing new versions, it's best to check out the official documentation to make yourself familar with mike.
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:
mike deploy --push --update-aliases 0.1 latest
Note that every version will be deployed as a subdirectory of your site_url,
e.g.:
- docs.example.com/0.1
- docs.example.com/0.2
- ...
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:
mike set-default --push latest
When publishing a new version, mike will create a redirect in the root of your project documentation to the version associated with the alias:
docs.example.com :octicons-arrow-right-24: docs.example.com/0.1