PREFACE

This post details the journey that I took in the making of this very website and blog setup. It involves a long path through remembering how web dev works, learning how to write man pages, learning how to write AWK scripts (and failing miserably at doing so), and finally automation of site generation and uploading said generated pages.

THE SPARK

I had the idea of making a website when I first purchased this domain. I knew that I would end up hosting it via sourcehut pages, which is what I currently am doing with the site. Other than that, it was a dark void of uncertainty. That was until mel of mutt.computer presented its site design in Aks' Matrix space. It was beautiful in its simplicity of being a man page, and that was the moment that I knew how I would design my website. mel had mentioned that it generated the site using OpenBSD's mandoc, and so I set off to make a site.

LEARNING TO WRITE MAN PAGES

The first step was to learn how to write man pages. I had written them before, but I used Markdown converted to roff for that, which really doesn't count. Therefore, it was time to learn some variant of roff. I went with Nroff, as that was what what GNU Emacs had a mode for. It didn't really matter though, as I used only basic macros. I quickly found a simple introduction on some university site, and I got up to speed fairly quickly; it took me something like 15 minutes to write a homepage for my site.

PAGE GENERATION

Then, it was time to turn my man page into an HTML document. It was a simple command, but the result left a lot to be desired. So, I turned to the AWK programming language to help me with formatting the generated pages (as I will get into later, this was not the best idea). But first, I had to learn AWK.

LEARNING AWK

I had quite the experience with learning this programming language. At first, I treated it as C, because it shared some of the syntax. This was a terrible mistake, and I ended up with immensely buggy and broken code, so I scrapped it and started over with a proper AWK tutorial. After I learned the flow of AWK's "pattern { action }" syntax, and learned some simple regex, it was fairly smooth sailing; I wrote up a script to inject CSS and manually indent entries. Pro tip: don't do that. I quickly ran into issues, such as having to detect whether lines in style tags were being parsed, if the line was body text or not, and other similar things that popped up. This very quickly became unmaintainable, so I did what I should have originally done: use a CSS stylesheet.

USING CSS INSTEAD

After my unmaintainable mess of AWK scripts, I went with a CSS file instead. I made some fairly minor changes to mandoc.css, and went from there. This made the site immensely more maintainable, and it has been fairly trivial to maintain since. The only compromise that I've had to make so far is having to write any hyperlinks present in the document as HTML tags and pipe them through sed, but that's not a real problem, all things considered.

AUTOMATING DEPLOYMENTS

Thanks to sourcehut's brilliant infrastructure, this was quite straightforward. All that I had to do was write a simple build manifest (which is available here), along with a script that generates and packages the site pages (available here), and I was off to the races. The site generates and gets uploaded on a Git push, and it's been quite painless since I set everything up.

CLOSING REMARKS

That's it for my first ever blog post. I hope that there are people that take at least some interest in my (hopefully coherent) ramblings. I'm sure that my writing will improve over time. Thanks for taking the time to read this!