Added support for versioning using mike

docs/creating-your-site.md

@@ -71,11 +71,12 @@ icons and much more:
 * [Setting up navigation][7]
 * [Setting up site search][8]
 * [Setting up site analytics][9]
-* [Setting up the header][10]
-* [Setting up the footer][11]
-* [Adding a git repository][12]
-* [Adding a comment system][13]
-<!-- * [Adding a landing page][14] -->
+* [Setting up versioning][10]
+* [Setting up the header][11]
+* [Setting up the footer][12]
+* [Adding a git repository][13]
+* [Adding a comment system][14]
+<!-- * [Adding a landing page][15] -->
 
   [2]: getting-started.md#installation
   [3]: setup/changing-the-colors.md
@@ -85,11 +86,12 @@ icons and much more:
   [7]: setup/setting-up-navigation.md
   [8]: setup/setting-up-site-search.md
   [9]: setup/setting-up-site-analytics.md
-  [10]: setup/setting-up-the-header.md
-  [11]: setup/setting-up-the-footer.md
-  [12]: setup/adding-a-git-repository.md
-  [13]: setup/adding-a-comment-system.md
-  <!--[14]: setup/adding-a-landing-page.md-->
+  [10]: setup/setting-up-versioning.md
+  [11]: setup/setting-up-the-header.md
+  [12]: setup/setting-up-the-footer.md
+  [13]: setup/adding-a-git-repository.md
+  [14]: setup/adding-a-comment-system.md
+  <!--[15]: setup/adding-a-landing-page.md-->
 
 ## Previewing as you write
 

docs/setup/setting-up-versioning.md

@@ -0,0 +1,97 @@
+---
+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][1]. When deploying a new version, older versions of your
+documentation remain untouched.
+
+  [1]: https://github.com/jimporter/mike
+
+## Configuration
+
+### Versioning
+
+[:octicons-file-code-24: Source][2] ·
+[:octicons-package-24: Utility][1] ·
+:octicons-beaker-24: Experimental ·
+[:octicons-heart-fill-24:{: .tx-heart } Insiders only][2]{: .tx-insiders }
+
+[mike][1] 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`:
+
+``` yaml
+extra:
+  version:
+    method: mike
+```
+
+This will render a version selector in the header next to the title of your
+project:
+
+[![Versioning][3]][3]
+
+_Note that you don't need to run `mike install-extras` as noted in the
+[official documentation][4], as [mike][1] is now natively integrated with
+Material for MkDocs._
+
+!!! quote "[Why use mike?][5]"
+
+    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.
+
+  [2]: ../insiders.md
+  [3]: ../assets/screenshots/versioning.png
+  [4]: https://github.com/jimporter/mike#usage
+  [5]: https://github.com/jimporter/mike#why-use-mike
+
+## Usage
+
+While this section outlines the basic workflow for publishing new versions, 
+it's best to check out the [official documentation][4] to make yourself familar
+with [mike][1].
+
+### Setting a default version
+
+When starting with [mike][1], 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 latest
+```
+
+When publishing a new version, [mike][1] 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_
+
+### Publishing a new version
+
+If you want to publish a new version of your project documentation, choose a new
+version identifier and update the alias set as the default version with:
+
+```
+mike deploy --push --update-aliases 0.2 latest
+```
+
+_docs.example.com_ :octicons-arrow-right-24: _docs.example.com/0.2_
+
+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_
+- ...

mkdocs.yml

@@ -162,6 +162,7 @@ nav:
     - Setting up navigation: setup/setting-up-navigation.md
     - Setting up site search: setup/setting-up-site-search.md
     - Setting up site analytics: setup/setting-up-site-analytics.md
+    - Setting up versioning: setup/setting-up-versioning.md
     - Setting up the header: setup/setting-up-the-header.md
     - Setting up the footer: setup/setting-up-the-footer.md
     - Adding a git repository: setup/adding-a-git-repository.md