~ePirat

Why switch to Mkdocs

The Icecast documentation used to be pure HTML. (Similar to the Icecast Website, which was pure PHP/HTML) As we made the decision to switch to a static site generator, Jekyll in our case, I rewrote the Docs in markdown, so they could be generated and styled appropriately, to look uniform with the Website design (which was made by Kai Kubasta).

Unfortunately Jekyll made some recent changes, that broke the way we generated the Docs for the standalone builds, see #3248. While it might be possible that the Bug will be fixed, or we could use symlinks as an alternative, jekyll has yet another issue: It is slow as hell. Maybe it is due to our very complex enumeration/indexes i.e. on the Docs index page for example:

{% for doc in docs reversed %}
    {% if doc.name != "" %}
        * [Icecast {{ doc.name }} Docs]({{ site.baseurl }}/docs/icecast-{{ doc.name }}/)
    {% endif %}
{% endfor %}

Another problem was that the Web template was not really made for Docs, and it did not really fitted the task good enough, in my opinion. For example there was no Menu but just a list of Pages on the first Page. So I decided to take a completely new approach and discovered Mkdocs, a tool build for building docs. While still in (early) development, it looks very promising, with a nice goal - simplicity.

Because the theme (currently Read The Docs, there are a lot more, but I thought the RTD theme is the nicest) is bundled with Mkdocs, we can now easily only have the markdown files in the sources, no need to have all the theme files there. This makes it possible that patches and improvements to the theme do not need any work on our side, just an upgrade of the Mkdocs version and it will work.

The only thing I am not quite sure is how we want to handle the different doc versions. Another thing I am not yet quite sure is how we will want to ship the docs. Ideally would be just including them in the source and building locally with mkdocs, but I think we can’t force every user that wants to have local docs to install Mkdocs.

One approach would be to make a branch where the generated docs are in and point to them using a submodule, so they can easily be updated. Another option would be to have them in a separate repository, with different branches. Or maybe we want to keep them in the web repo, but I don’t think that’s a good solution.