From hakyll to comrak based generator

November 15, 2026

Tl;DR: I decided to gradually switch from hakyll-based framework for this blog to comrak-based custom generator.

I'll migrate both HTML render of posts and RSS feeds in the following few days. You should not see any changes: all the URLs and UUIDs are the same before and after. Until I missed something crucial. I hope I did not.

The one exception will be the style of syntax highlighting in the HTML render of posts (and it will probably keep changing for a while more when I experiment with various backends).

Background

I used hakyll for about 13 years at least since first commit from 25 November 2013. It allowed me to bring up the trivial static blog site on GitHub Pages after I migrated WordPress-style platform where I used BlogLiterately.

haskell was my primary language to hack on hobby projects and hakyll was natural fit: it used pandoc to read rst, markdown and many other formats, it was able to render RSS feed.

Over time I added small features to hakyll-based generator like graphviz and gnuplot renders.

I had a few minor issues with hakyll:

My Attempt

I wanted to give rust a try. But I was not able to find a close equivalent to hakyll in rust land. I thought of building something similar: have arbitrary build rules for mostly markdown inputs.

I explored a few libraries that could parse markdown into AST, allow its mutation and render into HTML. I stopped on comrak and was pleasantly surprised by its API: It gave me everything I wanted. comrak has a ton of optional markdown extension on top of CommonMark.

comrak As markdown Render

comrak did not support tables understood by pandoc and I had to convert a few posts to more standard table extension. It also did not support ~~~ { .haskell } style of highlighting, I converted such posts as well.

After that I got almost identical HTML render out of markdown files I had. A few exceptions were " quotes, ' and ... where hakyll was more eager to use modern Unicode characters. comrak does not add as much of newlines between HTML tags.

maud As HTML Template Library

On templating side I was considering using tera to get jinja-style templates. But eventually leaned towards in-code templates using maud. maud has more natural way of embedding arbitrary rust code into templates.

My biggest template looks this way.

lol_html As an HTML Rewriter

hakyll was handling internal URL format conversion into relative (HTML) and into absolute (RSS) URLs. It took me some time to find a library that both parses HTML and allows its mutation via simple API. lol_html does not look too terrible.

My initial attempt at rewriting <img src= and <a href= links looks this way.

Other Libraries

A few other libraries I used are:

The Result

After about 2 weeks of evening I came up with something that generates very close HTML to the original (except the syntax highlighting). And this is my attempt as a single commit.

The whole site is built in 2 seconds (compared to hakyll-based 10 seconds).

There is no interactive reload /rebuild support for it. For me the inotifywait / cargo run --release is enough to implement the equivalent.

Have fun!