Setting up document versioning¤
Material for nbdev makes deploying multiple versions of your project documentation simple and convenient. It comes equipped with mike, a Python tool that helps deploy multiple versions of your MkDocs docs to a Git branch, ideal for hosting on Github Pages.
Enabling document versioning¤
Enabling document versioning in Material for nbdev is easy. Just add the
docs_versioning flag to your
settings.ini file with one of the
docs_versioning=minordeploys document in
<major>.<minor>format and reads the version from the
settings.inifile. Newer patch versions will replace previous minor versions (e.g. 1.0.1 replaces 1.0 and becomes the new 1.0 version).
docs_versioning=patchdeploys document in
<major>.<minor>.<patch>format (e.g. 1.0.0, 1.0.1) and reads the version from the settings.ini file.
We recommend setting
docs_versioning=minor to limit the number of
deployments while keeping all patch version changes. This also helps to
keep your Git repository small.
Regardless of whether
docs_versioning is set to
patch, the documentation for the pre-release versions such as
1.0.0dev will be deployed as-is.
Push the change to Git and wait for the
pages build and deployment
GitHub action to complete. After that, view the project documentation
URL to see the latest changes. To access different versions, use the
version selector in the header (a reference screenshot is provided
Deleting deployed pre-release documents¤
To delete all the deployed pre-release document versions, run the following CLI command from the project root directory and follow the on-screen instructions:
For additional configurations for managing the deployed document versions, please check mike’s documentation.