Material For MKDocs is great, but...
As I was explaining it 2 years ago in this post, the previous version of this blog was built with Material For MKDocs - and it's been a fantastic way for me to bootstrap this blog very quickly, 2 years ago.
However, I've been feeling the need to have more control over the way the content is rendered, and to have a more "hands-on" approach to the way the content is generated.
Also, even though Material For MKDocs is a fantastic tool for documentation websites, in my own case I felt that its very sleek and sophisticated User Interface was a bit too "industrial" for the blog I wanted to have.
A Django-based bespoke static site generator
11 years ago I started what became a personal tradition, which consists in building my resume with an over-engineered stack - because why not? 🤷
I recently re-built it, for the 5th time in 11 years 😄 : and this time I ended up building a bespoke static site generator on top of Django, only to generate 2 HTML pages - and their PDF version - from TOML data.
But it turned out that I really found that very satisfying to build! 😌
Django was not designed to be a SSG tool. But once you have your Django URLs set up, creating a static HTML version of the Views is actually pretty straightforward.
My build_static_files management command
Here is the code of the build_static_files management command I wrote to generate this blog as static assets:
Not the cleanest code in the world, but I only spent an hour or so on it...and it does the job! 😅
And by using Django, not only I get a codebase I very much enjoy working with thanks to the fact that it's written in Python... But I can also benefit from its rich ecosystem, with handy packages such as django-browser-reload.
Essential features I managed to replicate, actually without too much efforts:
- Rich code blocks: powered by the almighty Pygments and the Superfences extension. This is what also powers Material For MKDocs.
- In my code editor I use the Catppuccin Macchiato theme, and I wanted to have the same syntax highlighting in my blog.
- Live reloading in the browser
- Tags management: each blog post can have tags, and they can be used as a navigation mean
- RSS feed: I use RSS a lot, so it was important for me to generate a feed for this blog. Thanks to Django's Syndication feed framework, it was rather quick to implement.
Was it an efficient way to rebuild that blog in a few hours?
Giving a try to the fanciness of Astro... ✨
I fiddled a bit with Astro before deciding to roll my own Django-based version. But even if Astro is a fantastic tool, TypeScript a great language, and Node.js a more and more modern platform...
I felt that in this specific case, the "bazillion dependencies" aspect of it could become an issue in the long term.
For a team of developers working 7-8 hours a day on a codebase, managing the regular update of the dependencies is perfectly fine; however, for such a personal project on which I have limited time to spend, I thought that this aspect could have made the maintenance of this blog potentially challenging later on.
...Ending up betting on Python's stability
Compared to the JavaScript world the Python ecosystem is rather stable, and less dependencies-heavy: which could make it easier for me to maintain this blog's codebase in the long run.
That's my bet, at least - we'll see if it will pay off! 🤞
Bespoke SSG: the right choice?
But even in Python there is already a plethora of very good open source static site generators (some of them even being built on top of Django), so... was writing my own one the right choice, from a logical point of view?
Probably not, but hey - I had a lot of fun building it! 😄