New Blog version with MkDocs
In early 2021, at the climax of the Covid-19 outbreak, locked up in the apartment with my wife and 6-month-old kid, I decided to have my blog. I will not dive into the reasoning there. I decided that sharing my thoughts on the media platform I own was a good idea.
My initial requirements were:
- free hosting
- own domain
- control over the content and publishing capabilities
A static site generator, GitHub pages, and a custom domain name cover those points. Having a static site generator benefits in supporting the Markdown syntax, which I am using to write my notes. Plus, it is an additional technical challenge to configure and support that all by myself.
So my first choice was pretty obvious...
Jekyll era (2021-2022)
Jekyll is a very popular static site generator with multiple plugins and themes. It took me a few days to become familiar with it. My experience with building a test blog project in Django helped me there.
It possesses an entire ecosystem where you can do almost everything. And I was happy with that, except for one thing that appeared to be critical: Jekyll is written in Ruby. And I am a Python person.
So I found myself in an environment that I was not used to. You don't need to know Ruby to use Jekyll. But I felt uncomfortable while configuring or managing dependencies.
So I have made another obvious decision: I need Jekyll but written in Python.
Nikola era (2022-2023)
There are enough Jekyll replacements in Python, but none have such a big community and extensive support. So I had to look for something really supported by an open-source community.
Nikola appeared on my radar, and it seemed to be a good choice. The migration from Jekyll was seamless. I just had to change the URLs of my previous one and configure the redirection. Also, Nikola contains most of the features out of the box, so you don't need to install additional plugins.
I was happy with Nikola, and the only thing that made me consider another option: moving away from the blog post format. With the API Design series, I started collecting related essays into sections in a kind of e-book format. Technically, Nikola allows doing that. I just haven't found a theme I need.
As I already mentioned, Nikola does not have as much support as Jekyll does. So there are not many themes. Some of them are migrated Jekyll themes. So the only choice was to extend an existing one or create my custom Nikola theme. But I did not want to deal with CSS, Jijnja templates, and other UI stuff.
So I decided to consider different content platforms which can easily support my ideas.
MkDocs era (2023-now)
I keep an eye on documentation tooling, and MkDocs has been on my radar for some time. It is based on Python and is more straightforward than Nikola, where I could not remember a CLI command to create a new article in Markdown and sometimes struggled with configuration. Also, it has a built-in search which becomes necessary with growing content.
MkDocs is built for project documentation, and that is what I need. And it also has a fabulous Material theme with a fancy design, dark theme, and many other features.
The main challenge has been keeping the blog format as it is not something out-of-the-box. The Material theme provides blog capabilities but as a paid feature. The blog itself is net-negative, so I don't want to spend more than a domain price. So I have found a free alternative mkdocs-blogging-plugin. Just a few steps, and the blog is incorporated in MkDocs.
However, the content migration wasn't as seamless as it was from Jekyll and Nikola. I had to reformat each post's metadata and headings. Not a huge amount of work - but some routine stuff anyway.
What's next
I am happy with the current look and plan to explore different themes, plugins, and customizations. MkDocs' configuration is managed via YAML and has already expanded. So I will look for a way to split the configuration and automate adding new sections and pages.
Also, I am not sure that MkDocs will be my final choice. There is a particular joy in exploring new things, even when they are static site generators.
Take care,
Ilya