Mkdocs-material: Manage multiple versions of documentation

[bborysenko]

Will be great to have native support for jimporter/mike.

[squidfunk]

This request came up quite a few times and there are some projects which try to solve it (e.g. this by one of the MkDocs creators) but in my opinion it's not a solved problem. jimporter/mike is a start but after some research I found it relies on JavaScript for version selection - not great. Material strictly follows the rules of progressive enhancement so that core functionality works without JavaScript. If JavaScript is not available, versions cannot be selected. Also adoption seems to be quite low. For this reason I have no intention of supporting the project.

[squidfunk]

Also, you could implement versioning on your own using some shell scripts. You could build separate branches or tags of your git repository into separate folders and include a dropdown for version selection within the template. You could generate a Jinja template file which exports all generated versions as a macro. I used this technique to implement localization within Material, see:

https://github.com/squidfunk/mkdocs-material/blob/e5069bb21f603dd6ea1e7fc7cc64843d64b81428/material/partials/language/en.html#L1-L23

Within your macro you could export a list and then import the generated Jinja template and iterate that list. Importing works like this:

https://github.com/squidfunk/mkdocs-material/blob/e5069bb21f603dd6ea1e7fc7cc64843d64b81428/material/partials/language.html#L2

The fallback variable within this example can then be used as a variable within your template which you can iterate and generate a dropdown with the generated versions from. I hope that's helpful to you.

[squidfunk]

Closing as answered.

[jimporter]

For those who want to do this via mike, I've added support for the Material theme in https://github.com/jimporter/mike/commit/c2b7a2da18fa0e26cad43b9dc6a6e06c403abb82, which will be a part of mike 0.5 (to be released whenever MkDocs 1.1 is).

As a quick explanation to address the concerns raised above with how mike does things, I chose to use JS to build the version selector to meet a few goals: 1) old docs should link to newer versions; 2) once built, you should never have to rebuild docs for a version; 3) if the built docs are copied somewhere without versioning info, the version selector should go away; and 4) the solution should work on gh-pages (so no fancy server-side stuff). JS is the only way I could come up with that can do all that. Of course, not everyone cares about those goals, so perhaps it makes sense for mike to handle inserting the version selector for all the various MkDocs themes out there...