From hakyll to comrak based generator
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:
issue #610: no support for multiple output files from a single rule- no simple recipes of adding per-tag RSS feeds
- my lack of understanding of
hakyllinternals to add more advanced custom pages - my dwindled interest in
haskellecosystem - relatively slow site generation: about 10 seconds for my small input
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:
math-core: ascomrakwas not able to handlelatex-styleformulas I usedmath-coreto do build-time conversion.serde/serde_yaml: parse post metadatathiserror: ergonomic application-wide errorsurl: parse and normalize URIsglob: expand paths like"pages/*.mdas input to the generatorrssandatom_syndication: buildRSS 2.0/Atom 1.0feeds
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!