How to Use¶
This page is intended to be a step by step walkthrough on how to use this plugin in a typical environment. This will go through all the available config options as well as CLI commands available when you install this plugin.
Version 0.1.0¶
Lets say, you are building a shape library. version 0.1.0
of the documentation is for circles. You want a custom version selection page and you have an images
directory for images to be used for your docs which needs to be excluded from the version selection page nav (see here as to why). Your mkdocs.yml
will look something like this:
Example mkdocs.yml
for version 0.1.0
plugins:
- mkdocs-versioning:
version: 0.1.0
exclude_from_nav: ["images"]
version_selection_page: "version_selection.md"
nav:
- Home: "index.md"
- Circle: "circle.md"
- Version Selector: "../"
When you run mkdocs build
, your site
directory looks something like this:
Example site
directory for version 0.1.0
.
├── 0.1.0
│ ├── ...
├── ...
You then deploy the built docs to GitHub Pages using the command mkdocs-versioning deploy
. See here as to why this plugin has its own deploy command.
Warning
The site
directory should NOT be pushed to any GIT remotes (e.g. GitHub, GitLab, BitBucket etc) and should be ignored using .gitignore
file.
Version 0.2.0¶
The next version of the documentation you add documentation for triangles. The updated mkdocs.yml
will look like the following:
Example mkdocs.yml
for version 0.2.0
plugins:
- mkdocs-versioning:
version: 0.2.0
exclude_from_nav: ["images"]
version_selection_page: "version_selection.md"
nav:
- Home: "index.md"
- Circle: "circle.md"
- Triangle: "triangle.md"
- Version Selector: "../"
When you run mkdocs build
, your site
directory now looks something like this:
Example site
directory for version 0.2.0
.
├── 0.1.0
│ ├── ...
├── 0.2.0
│ ├── ...
├── ...
You then deploy the built docs to GitHub Pages using the command mkdocs-versioning deploy
.
Version 0.3.0¶
The next version of the documentation you add documentation for quadrilateral but, you move to a new computer You perform a git clone
to get a local copy of the repository from your remote but your site
directory is empty since the site is not pushed to the remote (and should not be). You can use mkdocs-versioning sync
which will copy the built docs from GitHub Pages into your site
directory. The site
directory should look exactly the same as the example site
directory for version 0.2.0.
Once you have a copy of your built docs, your updated mkdocs.yml
will look like the following:
Example mkdocs.yml
for version 0.3.0
plugins:
- mkdocs-versioning:
version: 0.3.0
exclude_from_nav: ["images"]
version_selection_page: "version_selection.md"
nav:
- Home: "index.md"
- Circle: "circle.md"
- Triangle: "triangle.md"
- Quadrilateral: "quadrilateral.md
- Version Selector: "../"
When you run mkdocs build
, your site
directory now looks something like this:
Example site
directory for version 0.3.0
.
├── 0.1.0
│ ├── ...
├── 0.2.0
│ ├── ...
├── 0.3.0
│ ├── ...
├── ...
You then deploy the built docs to GitHub Pages using the command mkdocs-versioning deploy
.