161 lines
11 KiB
Plaintext
161 lines
11 KiB
Plaintext
@document.meta
|
|
title: Making a Blog Using a Niche Markdown Language
|
|
description: How to make a blog using Norg and some random project from github
|
|
authors: [
|
|
Adumh00man
|
|
]
|
|
categories: [
|
|
Blog
|
|
Neorg
|
|
Nvim
|
|
Voidarc
|
|
Webdev
|
|
]
|
|
created: 2026-03-21T11:39:17+00:00
|
|
updated: 2026-03-21T13:41:48+0100
|
|
draft: false
|
|
layout: post
|
|
version: 1.1.1
|
|
@end
|
|
|
|
* 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.
|
|
|
|
Unfortunately, nothing ever goes to plan when linux is involved. The first indicator that my system wasn't going to work out was the fact
|
|
that when you rebuilt the site, the repo within the public folder was erased. This is nonsense, and I have already opened an issue so
|
|
that when it's fixed I have an excuse to remake the whole system.
|
|
|
|
*** Nginx Tangent
|
|
Nginx config is at the same time overly-complex and too basic.
|
|
It's like python. It looks easy on the surface, but when you get into it, does things in the most roundabout way possible.
|
|
Complaints about python aside, nginx is a nightmare to deal with on a usual basis. This is exactly why there are an infinite number
|
|
of management solutions for it, one of which I am literally using to host this site (shoutout nginx proxy manager my love).
|
|
Unfortunately not all of these solutions can host files at the raw level like I intend to, so here we are, once again, having
|
|
to waste hours figuring out why the css is being denied.
|
|
For future reference, the nginx config I'm using is as follows:
|
|
@code nginx
|
|
server {
|
|
listen 80 default_server;
|
|
listen [::]:80 default_server;
|
|
|
|
server_name _;
|
|
|
|
root /config/www/public;
|
|
index index.html index.htm index.php;
|
|
|
|
location / {
|
|
try_files $uri $uri/ =404;
|
|
autoindex on;
|
|
autoindex_exact_size off; # Displays file sizes in KB/MB/GB instead of bytes
|
|
autoindex_format html; # The standard web view
|
|
autoindex_localtime on; # Uses the server's local time for file dates
|
|
}
|
|
@end
|
|
To any experienced web developer, such as not myself, this would look like a war crime. Because it is.
|
|
This is 100% succeptible to every form of exploit one can think of. However, because I'm running this through nginx proxy manager,
|
|
I don't have to worry about such trivial things as "security" and "ssl". Everything is managed in a different docker container!
|
|
Thanks NPM.
|
|
|
|
*** Git tangent
|
|
Earlier, I said I wanted this to be automatic. And currently, it is. So, how?
|
|
I host my own shit. That's everything. Including Git.
|
|
|
|
Gitea is the least complex option that everyone seems to like enough to tolerate. It also has webhooks. And I have n8n. N8n is an
|
|
automation engine, that uses flows to achieve what can be done with basic intuition in a systemd service, or an assistant. Sadly, I
|
|
have neither the time nor money to hire someone to update git repositories for me, so I guess we're doing it with bullshit.
|
|
Gitea has the ability to trigger webhooks on a push event to a repo, and n8n can trigger commands when a webhook is triggered.
|
|
This has the side effect of letting me have a repo that, if pushed to, can trigger a webhook that opens firefox on my pc. As you can
|
|
tell, I shouldn't have permission to use automation tools. By hooking (no pun intended) n8n into gitea, I can run a command over ssh
|
|
every time the repo is pushed to, so the changes are pulled to the server automatically. The only caveat is that you can't minify
|
|
the build output, because if you do, any change will rewrite the whole file, which leads to truly insane git diffs. Such is git.
|
|
|
|
** The Final Result
|
|
Everything starts on my local machine. There is a folder in my Documents that contains the repo for the site. This is also set in my nvim
|
|
config as a Neorg workspace, so that I can make links between files, if I so wished. When I've written a post, I can build the site
|
|
on my local machine, an endeavor that takes a tenth of a second, and commit, with such entertaining messages as "initial" and "changes".
|
|
When said commit is pushed to my gitea repo, a webhook is triggered, telling n8n to ssh into server02 and pull the repo into the
|
|
www folder in the nginx docker container. Because nginx isn't 50 years old, all files update on the fly, and the new article appears
|
|
on the public facing instance.
|
|
|
|
See? web development is simple.
|