How it works¶
This page will describe how the plugin works by talking about the internal workings about the plugin. The following steps occur after a single mkdocs build command.
1. Building the main docs¶
1.1 Pre-build¶
The main documentation will be built into site/ in a folder equivalent to the version value in mkdocs.yml. The documentation will have the version number of the docs appended to the site_name value specified in mkdocs.yml.
Example built docs directory.
For version: 0.1.0, the docs will be built in the directory site/0.1.0/.... The ... means files (CSS, JS, HTML, etc) that are generated by mkdocs will be built into here.
If a custom version selection page is specified, it is hidden by prefixing the filename with a . (version_selection.md → .version_selection.md). A custom version selection page can be specified as a plugin config option.
Example mkdocs.yml with custom version selection page.
plugins:
- mkdocs-versioning:
version: 0.3.0
version_selection_page: "version_selection.md"
nav:
- Home: "index.md"
- Version Selector: "../"
Post-build¶
Once the docs have been built into its folder in the site directory, the custom version selection page (if specified) will be unhidden by removing the prefixed . from the filename (.version_selection.md → version_selection.md).
Warning: Renaming files.
The process of hiding uses Path.replace() from the pathlib module in order to rename files. Should the renaming fail, you may have markdown files with . prefixed onto the filename. A CLI command unhide_docs will remove the prefixed . from your markdown files.
2. Clearing out old version selection page¶
The plugin then, in the site directory, removes all the files related to the version selection page. Since the built docs are in their own folders within the site directory, we can delete all the files in the root of the site directory, folders explicitly specified by the plugin as well as any user specified folders using the exclude_from_nav config option for the plugin. This option allows you to specify a list of directories the the plugin will ignore. This will then leave us with site/ containing only folders named according to previous and current version numbers and in each folder, the previous and current built documentation.
Example mkdocs.yml with exclude_from_nav config option.
plugins:
- mkdocs-versioning:
version: 0.3.0
exclude_from_nav: ["images"]
nav:
- Home: "index.md"
- Version Selector: "../"
2.1 Why exclude_from_nav option¶
mkdocs allows you have any files related to the building of the docs in the docs directory, this includes non-markdown files such as a folder containing images, stylesheets and more. The default behaviour of mkdocs is to copy these folders into the site directory where the built docs live. Since the building of the version selection page depends on the root of the site directory, you may have additional options (e.g. images, stylesheets) appearing in the version selection page. This option will exclude these options appearing on the version selection page as different versions of your documentation.
3. Building version selection page¶
Since we are building the version selection page, we hide all the other docs by prefixing the filename with a . as mentioned in Step 1.1. If a custom version selection markdown file is specified, we then unhide the version selection page and rename it to index.md. If a custom version selection markdown file is not specified, the plugin writes a basic version selection markdown file.
After clearing the site directory, the only thing that should be left is a set of folders where each folder represents a different version. The folder names are used to create a nav in another separate mkdocs.version.yml file. mkdocs build is then triggered using the internal mkdocs API and the version selection page is then built into the root of the site directory.
4. Clean up¶
Once the version selection page is built, the building of the docs is considered complete and all the HTML, CSS and JS has been generated. Since we hid the documentation in Step 3, we then unhide the docs with special handling for the version selection page. If a custom version selection markdown file is specified, we then rename the version selection page from index.md to whatever it was initially called. If a custom version selection markdown file is not specified, we then delete the version selection markdown file as it was generated by the plugin itself.