Blogging In Gremlin Mode
Due to a number of factors, including the uncertain future of the
.io TLD, its growing negative connotations, and my
development focus switching to lil baby languages like Idris, I've found myself
in need of a new blog. I've been using Raku lately for personal tooling projects,
and decided to go full gremlin mode and write a hack together a cursed
static site generator in it.
Motivation
The domain change has obvious enough reasons, I've actually had this domain for quite some time and not been using it for much beyond email. The reasons for building a new static site generator are much more interesting.
As I've recently taken up working pretty heavily in Idris, I've had to deal with quite an interesting problem with sharing code snippets and writing documentation. Idris is a very... interesting language to provide quality syntax highlighting for, regular functions being able to appear in type signatures makes providing semantic highlighting quite difficult, but the dependently typed nature of the language also makes semantic highlighting extremely attractive.
Every source forge or off-the-shelf highlighting library I have tried either just completely has a stroke when presented Idris code1, likely due to using a slightly modified, but not entirely correctly done, version of Haskell highlighting rules, or has consistent syntax highlighting, but on low battery 2.
Fortunately, Idris helps us out here, the compiler contains a semantic highlighter built in, it can compile markdown files directly3, and there is even a tool, Katla, that can process source files, literate markdown or just plain Idris alike, and bake the highlighting into the html. Not so fortunately, this only provides us part of the puzzle. Katla only syntax highlights, it doesn't do any of the rest of the processing to produce html from markdown, and it's a little bit silly with also baking css styling into its output, but not allowing that css styling to be fully configured. For Idris heavy blogging, using literate/markdown Idris source files as the blog posts themeselves, I need a static site generator that has excellent support for mangling markdown and html at several points along the process.
I've been using Raku for more and more personal tooling tasks recently, and growing increasingly fond of it, it truly warms my little gremlin heart to use, so it was a natural target for hacking together a basic static site generator from stuff I just had laying around.
Method
The source code for this new blog is available here.
This code is not shared in the hopes that you will reuse it, it
is instead shared so you can learn from it, be inspired by it, or maybe
just be a little less scared of writing the cursed code that just gets
your current personal project done after you see the fresh hell I'm
shipping into my personal production. If I catch you using this code for
your own website, or even worse, asking for help using it, I will
personally revoke your ability to type the letter f.
This is, overall, a very basic markdown based static site generator, with the markdown → html conversion being handled by pandoc. Some handrolled html and css is glued around the pandoc output, and some very basic html generation is done for the index and archive pages. To allow the literate Idris posts to live in a proper Idris package, the site generator assumes no structure to the markdown files, and stores metadata about posts, including the location of the source files and what type a given post is, in a directory structure containing JSON files.
The really fun part is processing the output from Katla. Katla's markdown mode is used to provide syntax highlighting for the Idris code blocks in a literate Idris post, the markdown output from Katla is fed into pandoc, and from there, I go full gremlin mode and just completely mangle the html with regexes4 to remove the katla generated css, massage the generated tag structure to match the css I want to write, and clean up a bizarre issue where this pipeline is erroneously adding way more backslashes than it should to escape some characters.
The generation of the Atom feed is actually handled somewhat properly, using a proper XML library and everything!
This is all horribly, horribly cursed, and should probably never see the light of day, but because this is just for me, and I control all the inputs to the system, It's Fine ™.
Fun notes
At the time of writing, my IdrisPost.rakumod module, for
reasons unknown to me, breaks forgejo and causes a server-side index out
of bounds error when you try to use the source code for that module, so
sorry if the above link takes you to an error message instead of the
source code. If this isn't fixed the next time I get around to updating
forgejo on my server, I'll file a bug report I promise.
The handrolled css for this site is light-mode/dark-mode aware, and, at the time of writing, uses selenized5 white/black for the main content, and dark/light for code blocks.
Forgejo is frequently guilty of this↩︎
Sourcehut falls in this category↩︎
Idris's Literate Programming support is honestly amazing. Not only can it handle markdown files exactly as if they were the source files you could get by extracting the idris code blocks, it supports several other formats, like org mode, latex, and even typst now.↩︎
I can not be stopped and I will not apologize↩︎