How I Wrote This Website
Date:
To create this version of my website, I used a technique called Literate Programming. This method requires a strong marriage between documentation and the programming language(s) themselves. The purpose for this marriage is to create a program that is as easy to follow as a book.
You may also be aware of the "Clean Code" paradigm, where many believe that comments and/or documentation is superfluous and a symptom of poorly written code. They feel like the code should speak for itself. I am kind of in both camps.
While I enjoy the idea of my literate program being easier to understand because of the documentation effort, without care, it can rot as fast as the code it produces. While writing literate programs I try to focus on brevity and organization rather than over-explaining what each thing in my program does. Anyway, with all that in mind, let's get into the details.
The documentation of choice for my literate programming is Orgdown, the documentation language of Emacs Org Mode. The venerable Org Mode is a powerful note taking, task managing & literate programming powerhouse. It is capable of organizing a program into sections, displaying code in code blocks, and concatenating all of those code blocks into output files. This concatenation process is called "tangling." You may also "de-tangle" changes in source code files back into the documentation.
With the power of Orgdown, I can organize, describe and emit all of the files required for my website generator to work. My website generator of choice being Emacs with Org Mode itself! Org Mode comes with powerful abstractions to publish Orgdown files into nearly any useful format, including but not limited to HTML files.
Having come from using tools like Hugo, Org publishing feels like it has far fewer features. There are some minor hangups with generating the HTML content. It doesn't always understand the context for which hyperlinks are meant to be used on the Internet and I had to employ the use of advanced text filters to adjust them for a few special cases. For the most part the generator worked out of the box. I am still learning all of Org Mode's publishing capabilities and I'm having a lot of fun with it.
What I've ended up with is a website that is pretty simple and feels old school. There's minimal CSS with no @media queries, no JavaScript, no "navbars." It looks a lot like my Emacs because I based the CSS theme off my Emacs theme.
Wanna leave me some feedback? You can't! Not here, at least. There are no forms, no back-end logic and no data collection. Feel free to message me on Mastodon or BlueSky if you'd like to connect or share any feedback. To view the literate program that is this website, follow the source code link at the bottom of the website.
I'd also like to give a big shout out to David Wilson and the System Crafters community for the inspiration and sharing many of the cool ideas I implemented here.