Mkdocs Gradle plugin release
A new version of mkdocs gradle plugin just released featuring:
- Documentation version selector
- Dark theme switcher
- Documentation aliases
Now generated docs could look like this:
Some time ago mkdocs-material introduced version switcher, but it requires mike tool usage for publication. That was a problem because the plugin uses its own custom publication mechanism (much easily customizable from gradle).
But, it appears, all that mkdocs-material needs is just a versions.json file, describing all available versions. The new plugin version now always generates such file (based on gh-pages repository folders).
The interesting moment in the versions.json generation was versions sorting: there are no pre-defined patterns of possible versions and so versions should be sorted as strings. The natural order is not a good option because it does not count numbers well: 1.10, 1.11, 1.9. The solution was found in not (yet) accepted JDK improvement: JDK-8134512 (actual JDK extension JDK-8213167 and the code itself). Of course, this solution is still not ideal: for example, it always prioritizes SHAPSHOT or RC versions over releases (1.0-rc.1 > 1.0 due to length), but still, the result is good enough.
Another aspect, missing in the publication mechanism, was documentation aliases. The most common example is "latest" alias always pointing to the latest documentation. With it, users could use links always pointing to the most recent version. For example:
without an alias, a user could use only: http://my-url/1.1.0/some-file.html
and with alias: http://my-url/latest/some-file.html
To see it "in action", open root documentation link and it will redirect to the latest folder.
There are more useful applications for aliases: for example, documentation for developing version could be aliased as dev or alias could lead to the latest major version like 2.x (again, could be handy for user links).