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 following values:

1. docs_versioning=None disables versioning.
2. docs_versioning=minor deploys document in <major>.<minor> format and reads the version from the settings.ini file. Newer patch versions will replace previous minor versions (e.g. 1.0.1 replaces 1.0 and becomes the new 1.0 version).
3. docs_versioning=patch deploys 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.

Note

Regardless of whether docs_versioning is set to minor or patch, the documentation for the pre-release versions such as 1.0.0rc0 or 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 below).

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:

nbdev_mkdocs delete-pre-release-docs

For additional configurations for managing the deployed document versions, please check mike’s documentation.