I decided that I wanted to get better at writing. It’s something that I’ve always been weak at, so I should practice more. And what better way to practice than have a blog.
I had a couple of requirements, I wanted to write in markdown and I didn’t want to have to host anything myself. Markdown because I’m comfortable with it and use it often. Hosted by someone else because although I’m capable of doing it myself, I can’t be arsed. I get enough of that sort of thing in my day job.
Platform/tool/software 🔗
I decided that I’d use a static site generator. I’ve used one before so knew roughly what I was getting into. There are a lot of options for static site generators written in a multitude of languages. Most recently I’d heard a lot about Hugo. A quick check of the documentation had me confident that it should be easy to install and use, so I went with it. I could write my content in Markdown and because it generates HTML it should be pretty easy to host.
Hosting 🔗
For hosting “plain” html there are lots of options. I really didn’t want to have to maintain my own infrastructure though. I’m lazy and I don’t want to be a sys admin in my free time, I’ve done enough of that in the past. I have used github pages in the past and it ticks all the boxes for me. I don’t have to run my infra, and automating publishing is really easy. But I’m getting a bit fed up with github at the moment, so I went looking for other git forges with pages. I found codeberg which have their own flavour of pages and you can run actions, which allows for the automation I wanted. They make the point that their pages shouldn’t be used for anything critical, so my writing fits well.
Implementation 🔗
Having decided the what and the how I started to put it together. Hugo’s starter doc are pretty good, gets you up and running locally pretty quick. But I hadn’t realised that I was going to take forever to choose a theme. Once I’d made my choice I found that it was broken slightly with the newer version of Hugo. I had to fork the theme and fix it, sigh. Then there was the way adding images worked with running the site on a path. It wouldn’t do relative image urls. I futzed around a bit and just hardcoded the paths, was it the right fix? probably not, but it was quick.
Setting up a repository on codeberg was pretty easy. I was able to find an action that I could use to auto publish the generated HTML.
You can see the workflow file here
I had this initial version everything running on a path on codeberg pages, “/tabstop/”. I wanted to move it to my own domain. Surely it shouldn’t be hard to move to a custom domain, there is documenation. And overall it wasn’t once I figured out I was missing a step. I followed the project site, apex domain instructions but nothing was working. I was getting SSL errors when going to my domain. I double checked all the DNS settings, I’d tried using A/AAAA records which is the second option, so switched to the ALIAS record method. Still not working. Then I came across a an issue on codeberg that helped, 1680. Reading through that I realised that I needed to have the .domains file copied into the pages branch. So I modified the workflow to copy the file post build but pre artifact upload. This initially didn’t work because the artifact upload doesn’t include hidden files by default. Once turning that on it all started working.
All in all not super hard but more work that I initially hoped for. Fingers crossed it will be low maintenance.