110 lines
5.8 KiB
Markdown
110 lines
5.8 KiB
Markdown
# 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>
|