This blog (and my whole website) is now driven by Mkdocs 🔗

Posted by Médéric Ribreux 🗓 In blog/Blog/

#web #auto-hébergement

After eight years of full service under Ikiwiki, this website is now driven by mkdocs. As a report of service, I'll conclude that Ikiwiki is a very clever piece of software. I think I need to underline that I still haven't found any other static web engine up to par with Ikiwiki. Of the (more than) 10 engines I have tested or evaluated last year, absolutely not anyone was natively able to handle all of the features requested for the building of my website. And I was far from using all of the features offered by Ikiwiki.

If Ikiwiki is very good, I faced lots of problems with it over years. The first one was a performance problem. It took more and more time to build or refresh my website as I wrote more and more articles. Then, by disabling entirely Javascript on my website, I was forced to rebuild everything each time I published an article. But the most important problem was that I wasn't able to understand Perl anymore. 15 years ago I coded some scripts in Perl (I even bought a book about Perl 5) and was able to do things in this language. But not anymore: whenever I see Perl code, I tend to flee. I tried to circumvent my problems by reading Ikiwiki code and was sad that it was too much complicated and required too much brain effort to understand anything.

For me it was a clear signal to move to something that I could hack. So I focused on Python driven static website engines. Python is the language I used the most, at work and definitely at home and I feel confident in it. I am far from being a Python expert but I am reassured when I think about some lines in Python I wrote in the past which are used every day by QGIS users.

As a review, I tried to simply rebuild my website from scratch, using only the Markdown content from Ikiwiki (and sometimes rewriting it using simple tools like sed). I tested Pelican, Nikola, Lektor. I only managed to cover 100% of required features with mkdocs and some Python code of my own.

Here is a list of the required features used in this website:

Mkdocs is a generic web engine, more focused on documentation websites than in blog articles but sufficiently versatile to do the job for me. I was also able to remove all of the crappy parts of it (mostly Javascript and CSS shit) to rebuild my website nearly like Ikiwiki. I just modified the CSS. It took me probably two to five days to code/rewrite articles/modify metadata. But at the end, mkdocs was the most satisfying static website engine. Furthermore, it is blazingly fast: I can rebuild my whole website in less than ten seconds on a eight year old computer. It is about ten times faster than Ikiwiki.

mkdocs is far from being perfect but I am feeling more confident in my ability to fix things on it rather than with Ikiwiki. I have already understood most of the main code and written a dedicated plugin on it. Furthermore, the base code is relatively compact compared to Ikiwiki.

Well, for now, I will stick with mkdocs; probably for 10 years until something better, lighter, faster and simpler to use will surface.