Making a Blog Using a Niche Markdown Language

March 21, 2026

Nonsense Preamble

Neorg is a markdown Language that is Org mode but with some different shit in it. It is supposed to be a replacement, but since I never really used Org mode in the first place, that doesn't really apply. However, after using it for a whole 10 seconds, I decided I could never go back to using Markdown ever again. Norg was just a superior language in almost every way, except widespread support. There are a plethora of plugins, but a distinct lack of real world uses, or even good utilities for using it outside of nvim, like it was intended. However, there was some random thing called Norgolith, that did apparently exactly what I needed it to, so here we are.

Norgolith

Apparently, as often happens on the internet, someone had thought of the same genius idea I had and made it already. I was fully prepared to have to spend 3 weeks making a custom solution in Javascript that would end up half baked, but fortunately someone had already done all the hard work for me!

A static site generator is exactly what it says on the tin. It takes in some manner of arbitrary markdown script, and spits out some html that can be served to the end user. Pretty simple if you ask me. Well, if you had asked me before I started that is. As things often go, I did things completely wrong the first time round. I assumed that, because I didn't know what generator meant, Norgolith would have some docker compose version that i could just shove some norg files into and it would handle the rest. That's literally what it says on the homepage, after all. Something something Sod's law. Turns out that I would have to use more than just docker in order to get something like this working.

The First Hurdle

When I first downloaded the app in question, the first problem I encountered was the blatant lack of documentation upkeep. As the docs indicated, I tried running lith serve to serve the app. Turns out, the command had been renamed to lith dev quite a while ago. The command itself hadn't changed, nor the functionality, just the name. Of course, this was as simple as I thought, because I tend not to think much when faced with simple concepts. The same thing happened when I decided on a whim to host an email server, which still to this day has not recieved a single email from anyone other than myself.

The First Attempt

Once I had realised that the docs were completely unreliable, I decided that it would be a great use of my time to try and follow them anyway. The creator (amartin) had done the usual blogger thing and hosted all the docs on Norgolith, which would be fine if Norgolith had a search function. Unfortunately, it does not, nor does it have a nice page where you can see all the pages that are outside of the post directory, which just so happened to be every page of the docs. In fact, on the doc site, there is a dead link to a theoretical post example, which was removed on github but not from the header.

Strange.

I initialised a Norg site in some random directory, still believing that I could host the whole thing self-sufficiently, and instead of reading more than the code snippets in the github readme, I set off immediately to make a docker container that would serve the app. By that, I mean I asked gemini and had to wait for the app to compile on my very old server. After a while, I gave up and went to do something else, because I'm lazy. The first site was a failiure.

The Second, More Successful, Attempt

For some reason, when I woke up the next day, something came over me. I realised that when I had run lith build, it had produced a static site , which made me realise that I might be stupid. I realised that using some complex webhooks, i.e. 1 webhook, I could have a local copy in norg form, and then have a git managed copy of the generated site. Shouldn't be too difficult using n8n, the only useful app I've ever installed. Before that, though, I could use the dev server for what it was actually intended for, and make a first post to style.

Styling, and my newfound love-hate relationship with Tailwind

Tailwind css was created in order to solve the really hard task of adding border-radius: 3; to anything on a website. Why use readable syntax when your css can be spread across 15 different files and require an interpreter, after all. Tailwind is based on immutable classes, and too many variables for my liking. Instead of using color: white; in a css file, you could apply the class text-text to every div on your page, provided that you set the --text variable to white beforehand, in a different file, and managed to compile it using the right version of tailwind. Because of the fact that I use nix, btw, the default package for tailwind provides tailwind 3, that requires npx nonsense packages in order to function, and also doesn't recognise half of the functions that are in the theme I ~~stole~~ borrowed and changed, as stated in the licence I definately read.

On my first try, having never used tailwind before, I decided to just edit the files and see what happened. Of course, because the tailwind.css file isn't the one that gets applied to the frontend, and nothing changed, so I gave up (I know, shocking).A On a retry, I used the tailwind_4 package, and it worked perfectly first try. Who could've guessed, I guess. Once I realised tailwind was actually pretty simple, and I was the problem, I managed to import my fonts and a Catppuccin css variable file, hence the current color scheme. Pretty nifty, huh.

In short, fuck tailwind. But also, use tailwind for everything you possibly can.

The Dreaded Backend

The concept was simple, as all concepts are, expecially when the person making said concept has no concept of how to properly make concepts. This person turned out to be me, and the concept was fairly simple. Have a primary repo, that contained 2 submodules. The primary repo would house the whole site, config, themes, etc. The first submodule would contain the raw .norg files that are in the content/ directory, and the second would have the output html files that would need to end up on the server serving the service that is currently letting you read this right now.

Said service would be a simple nginx docker container on some random port, that serves whatever it is asked. In order for such a service to be viable, I don't want to have to manage it manually. Instead, I can use a webhook to pull the html repo whenever there is a new commit. This could also be on a timer, but instant gratification is better.

Posts in blog

Categories

Posts in neorg

Posts in nvim

Posts in voidarc

Posts in webdev

Voidarc

Recent posts