Back to main page

Migrating my blog to Makko

I migrated from Jekyll + Chirpy to Makko, it's worth it.

My first website was Jekyll-powered

When I was finishing my Master's degree, around 2024, I thought it would be a good thing to have a personal website. Something like a browsable resume of sorts. I think at the time I was more interested in how it could carry me professionally than anything else. So I started experimenting with what was available on the github pages. I found Jekyll and, after a bit more searching, the Chirpy theme. It worked quite well, it was a modern webpage and, for what I needed at the time was good.

Slowly, the project became a personal blog, under my civil name. I was torn between writing what I wanted to write and knowing that it would follow me in my academic and professional life. And that made me quite uncomfortable.

I still wrote a few articles, here and there, but little by little, the aim shifted, from a very professional page to a more personal blog. The change mostly occured when I order my domain name. Suddenly, this weird personal/professional coupling became an irreconcilable clash. I wanted a space that was more me. This would result in both trying to remove most mentions of my actual name and trying to get a more custom render.

Falling out of love with Jekyll

And here's where Jekyll + Chirpy sucked. The project is such a heavy soup of div inside div inside more wrapper div that it's basically impossible to patch the theming or templating without putting heavy work in understanding the structure of the theme.

What's more, it's very feature packed. CDN support, analytics integration, comment integration, Javascript everywhere. I didn't need any of that. In fact, I value lean websites. Sites that go straight to the point. Projects that can be the love-child of one determined individual without months of experience in webdesign, Liquid, SCSS, JQuery, and all that. Many neocities websites capture this simple (and retro) vibe and, while I'm not great at design in general, I'd be fine with a simpler structure.

Looking for alternatives

Realistically, what did I need? I wanted to:

The hard part seemingly is the Markdown to HTML conversion. I know Pandoc can do it moderately well while also converting the inlined LaTeX. And so, for a while, I thought about making my own static website generator. I debated how I would make it, starting with "What language should I design it in?" The easy answer is Python, I know it quite well. But I don't like the direction (cough cough AI cough cough) the language is taking and am always looking for new skills to learn. So I was thinking about Perl, Rust or Zig.

Heaven-sent Makko

One day, as I was browsing Fedi, I found a post of someone asking for recommendations about static website generators and Makko got mentioned. I took a look and, what was my surprise when it looked like exactly what I wanted to do, but already done.

I'm not one to reinvent the wheel, especially on projects which seem to share my values, so I took the pink rabbit software for a spin. With very little modification of the YAML front matter, Makko generated a very decent draft of what I wanted. Everything is simple. Simple HTML, simple sample CSS and templates, no Javascript. It was such a breath of fresh air.

I quickly realized that, for all its qualities, Makko had two main issues for me:

The next sections on how I fixed these issues are re-narrated versions of the README of the website source.

Post-processing articles

Looking through Makko's documentation, I see that there are callbacks called when articles are created, edited, etc. Based on what the project's site is showing, I don't think it's really meant to edit the files, moreso to help with deployment, version management and other administrative tasks.

Without any care for the intended usecases, I hack away a couple of Python scripts leveraging LaTeXML and Pygments to render LaTeX to MathML (which should be better for accessiblity than a SVG with alt text, in addition to being lighter in ressources) and highlight code blocks.

Code highlighting

See source code here

Parsing HTML is a complicated task. Tokenizing who knows how many languages to highlight keywords as well. So, we delegate. beautifulsoup4 makes parsing HTML and navigating the DOM a breeze while pygments has so many lexers, added with a HTML formatter, it would be silly to redo everything.

I'm not a big fan of pygments however, for the simple reason they seem to be very chill with AI usage for their codebase. I don't know of any other library that does what pygments does however, so I guess we're stuck with it for now.

LaTeX to MathML rendering

See source code here

Converting the LaTeX to MathML is not the difficult part. Well, it should be, but thanks to the magic of reusing software, we can delegate that to the LaTeXML project. We need only to find the math blocks.

Since the input I have at this point is the HTML file rendered by Makko, the math contents is stored in <x-equation> tags, with a type="display option for block equations.

And so, I find all the opening tags (of both kinds) and the closing tags using regular expressions (even though, given that there are exactly three fixed patterns we are looking for, there could have been simpler ways to do the lookup), ensure no tomfoolery takes place (such as mismatched tags) and sort all the code that isn't <x-equation> tags in either "generic", "equation" or "block equation" types, with their order of appearance.

Finally, all equation and block equation get converted as they should and inserted back into the HTML file. Writeback everything and bingo.

The only "problem" with this approach is that using latexmlmath to render one equation at a time takes a long time. Every call of latexmlmath does a lot of costly LaTeX engine initialization. It would be faster to make one LaTeX file with all the equations, convert to MathML and extract the equations back. But honestly, I don't mind waiting 30 seconds for the generation of one page once in a while so I'm fine with it.

Patching Makko to get posts contents in Atom feeds

Here's the big, scary part. Hijacking the feed generation process to include the contents of the articles in the feeds. It's probably doable to do something with callback scripts, but I leave that exercise to someone else, no thanks.

It was my first time reading or coding in Zig. And what a pleasure it was. It feels clean and sober, I respect that and will probably take some more time in the future to delve deeper in the language.

The good thing is that the feed generation functions already have the body of the articles passed to them. So, we just add a <contents> tag, fill it in with the XML-escaped version of the article and roll with it, right?

Not so fast! The problem with including HTML in feeds like these is that not every feed reader will parse it as such and you end up with text that's difficult to read. Even morseo when the escaped character are not interpreted back. That's the case of the reader I use (newsraft). And, in general, plain text is just more compatible. For stuff like images, links, tables etc, the full webpage is still there.

So, I decided to simply strip all HTML tags before including the post contents in the feed. I don't do any kind of typesetting based on the tags, I don't extract links or alt text or anything. I wanted something simple. With that in mind, I only need to check whether a character is part of a tag or not.

The implementation is done with a 2-state stack automaton. Basically, we read every character one by one and depending on what character we read and what state we're in, we can do any of these:

The three states are:

In a normal state:

In a Tag state:

In practice, the code I implemented checks for nested tags (structures like <some text </why would this happen>>), but this is not valid HTML so I didn't include it in this explaination.

We could make the state machine a bit more complicated to keep track of:

With the HTML tag stripper in place, the contents of the posts can now by included in the feeds!

Styling the website

Homepage layout

If there was one thing about the Chirpy style I liked, it was the sidebar with the avatar. So I extended on this idea to add a little bio and some credits.

I spent way too much time trying to fiddle around the layout to make it look good on both wide and narrow devices. In the case of narrow devices, I wanted to bio to go above the article list and the credits to go below.

The solution I ended up with is to have a grid layout which changes on @media all and (max-width: 700px).

Conclusion

All in all, this is about a week worth of tinkering. I'm quite happy with the results (except with making it work with NixOS, but that's probably a me problem and the topic of another post). Makko is a great tool. Its simplicity means it's so much more customizable. I really enjoyed working on extending it for my purposes and will probably look to contribute to the project once in a while as well!

by CelestialSynapse