website/projects/Markdown/MyNewBlog.md

# 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](https://github.com/idris-lang/Idris2), I've found myself
in need of a new blog. I've been using [Raku](https://raku.org/) 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 code[^1], 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 directly[^3], and there is
even a tool, [Katla](https://github.com/idris-community/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](https://git.stranger.systems/thatonelutenist/website). 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](https://pandoc.org/). 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 regexes](https://git.stranger.systems/thatonelutenist/website/src/branch/trunk/lib/DB/IdrisPost.rakumod)[^4]
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 selenized[^5] white/black for the main content, and dark/light
for code blocks.

[^1]: Forgejo is frequently guilty of this

[^2]: Sourcehut falls in this category

[^3]: Idris's
    [Literate Programming](https://idris2.readthedocs.io/en/latest/reference/literate.html#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.

[^4]: I can not be stopped and I will not apologize

[^5]: <https://github.com/jan-warchol/selenized>