Building a Markdown-based blog

UPDATE: This blog is actually... no longer powered by Material for MKDocs 😄

Two years later, I ended up rolling my own static site generation solution.

I documented the why and how there:

A new engine for this blog (6th May 2024)

I'll still keep this article here, as it might be useful for someone who just wants to set up a blog quickly with Material for MKDocs - which is a great choice to do so :-)

I've put this devblog online the other day, but haven't documented how I built it yet - which will be useful for my future self if I have to do something like this again, and could potentially be of some help for other people. Here is how I determined what was the quickest way (for me) to put a "devblog" online as quickly as possible, without hours of setup. 🙂

Why not Next.js?

My natural "go-to" option would be Next.js, with its SSG capacities and built-in support of MDX. Also, I like managing this kind of stuff manually myself - i.e. traversing a folder of Markdown files at deployment time when Vercel runs npm run build, sorting my content, providing the result to getStaticProps... It's genuinely fun 🙂

However, even though I really enjoy doing this kind of work on the Node.js side there is a drawback for me: I would then have to build the user interface myself.😔 And my skills in terms of design being as bad as they can be 😅 , I really don't want to work for hours on the React side only to end up with an ugly UI.

There are open source or free turnkey blog templates for React/Next.js, of course, but I haven't really seen any of their design that I like (that's obviously highly subjective).

Hence my second option...

Material for MKDocs

Or:

Using a documentation engine to make a blog, what could go wrong? 😅

(spoiler: it was quick and fun to do, I regret nothing :-)

MkDocs and its modern Material theme

MkDocs is a static documentation generator, programmed in Python and configurable in YAML, created (if I'm not wrong) by Tom Christie - who's also behind huge Python projects like Django REST Framework or Starlette.

Question

I don't know the history of MkDocs, but I guess Tom Christie created it to document Django REST Framework?

Material for MKDocs is a theme for MKDocs, based on Google's Material UI guidelines, that make MKDocs look much more modern (as great as the project is, MKDocs' default theme shows its age nowadays).

Why they can be relevant to build a simple devblog

Neither MKDocs or Material for MKDocs are designed to make blogs (even though it's on the roadmap), but they have some common aspects with what I wanted to do:

Treats folders of Markdown files (with YAML metadata in their header) as a tree of Web pages
Built-in ability to publish static pages to GitHub Pages, for free
Simple but good-looking user interface theme by default 🎨 , so I don't have to fiddle with HTML and CSS but can focus on the content itself
Made with a technology I'm familiar with (Python in this case)
Excellent syntax highlighting (will be useful for my snippets :-), powered by Pygments

The plugin mkdocs-awesome-pages-plugin also helps, so I don't have to build the whole navigation tree manually in the mkdocs.yml file 👌

Quick setup of "Material for MKDocs as a blog"

I found two good resources explaining how to use Material for MKDocs as a blog engine, so I could hit the ground running (I really didn't want to spend hours on this setup 🙂):

The documentation of Material for MKDocs itself if really nice, and pragmatic - explaining very simply for example how one can publish the generated static HTML content to GitHub Pages:

https://squidfunk.github.io/mkdocs-material/publishing-your-site

It was looking doable! :-) Let's give it a shot, with a quick Python setup:

$ mkdir devblog && cd devblog/
$ pyenv shell 3.10.4 # (1)
$ python -m venv .venv # (2)
$ source .venv/bin/activate # (3)
(.venv) $ pip install -U pip poetry # (4)
(.venv) $ poetry init # (5)
(.venv) $ poetry add \ # (6)
    mkdocs-material \
    mkdocs-awesome-pages-plugin

let's use a recent version of Python
create a virtual env in a ".venv" folder
activate the virtual env: from now on the Python-related commands we type only impact the ".venv" folder
in the virtual env, update pip and install the Poetry package manager
initialise Poetry for this project
ask Poetry to install the few packages we need for this blog

Now all I had to do was to follow what these 2 articles were explaining, browse a bit the Material for MKDocs documentation, use the really nice icons and emojis search provided by this documentation (it's the little things ^_^)... and a couple of hours later my first blog post was online, automatically published by a GitHub Action every time I push my main branch! ✌️

My quick personal touch 👌

Compared to these two very useful articles, my only personal touch was to add two things I always use in my projects:

The modern package manager Poetry rather than pip (the Python default one)
Create a Makefile at the root of the git repository, for the common tasks

I also wanted to automate the "posts table of content" on the blog homepage. I chose to do it myself, mainly because it's the kind of things I really enjoy coding ^_^

The logic lives in the my_plugins/blog_toc/hooks.py Python file, plugged to the MKDocs generation lifecycle with the nice mkdocs-simple-hooks package for the sake of simplicity 🙂

Later on I added the generation of a RSS feed when the blog is built, powered by the mkdocs-rss-plugin package.