2025-01-14
Warning: while I will do my best not to make too many assumptions about the tech savviness of my readers, this is a deep dive into the tech I use to run this blog.
Someone asked what technologies I'm using to host this blog. While I have a background in web development about 20 years ago, I'm extremely rusty in almost all ways that matter. I also know enough to know that the modern web is a hellscape of javascript frameworks, typescript pre-processors, and Beelzebub knows what else. This is a goddamn blog. It's text and images. This shit could run on a calculator. I don't want to have to think too hard about adding new text and images.
I'd rather not have to monkey with writing HTML code just to post a new entry, and I'm reasonably familiar with Markdown, so a static site generator just made the most sense.
TLDR for the people who's eyes are already glazing over: I write some plain text markdown files, and then I run an app called Zola that turns those text files into HTML files I can upload to a web server.
There's a lot of SSGs out there, but most of them are written in Node or Python or other languages which have a tendency to either mess with your system's environment, or I would need to install the SSG in a virtual environment. Both of those options sound like extra headache I do not want to have to think about.
Zola is a single binary executable. Everything it needs in order to run is baked into a single file. No mess, no fuss.
Warning: There is no GUI for Zola.
If you are looking for a drag-and-drop solution with pretty buttons and such, Zola is not that. If you are familiar with command-line stuff, setting up Zola will be fairly straightforward. Command-line skills are well beyond the scope of this blog post. 😅
The rest of this post assumes some familiarity with the particulars of web hosting, HTML, CSS, Javascript, and command-line tools.
This page pretty well walks you through how to get started with Zola.
I'm not gonna reinvent their documentation. Instead I'm gonna mostly focus on the things that tripped me up initially.
In the root of your freshly initialized site folder there's a config.toml file. This is where your customized settings live.
I added the line generate_feeds = true so I could have an Atom RSS feed. This is a blog after all, people should be able to subscribe to it. Other than that, mostly I just disabled features which I knew I wouldn't need, and modified some file paths since the blog is a sub-section of skullvalanche.com, rather than the full thing. You can see my full config file here
The other things that proved to be non-obvious involved where to put files when writing blog posts.
The Zola docs walked me through setting up template files, and that was all fine, but I wanted to put a javascript file somewhere. I also wanted to put a CSS file somewhere. Where do those go? How do I reference them?
There's a folder named static which is for - you guessed it - static asset files. Things which aren't markdown to be rendered, but still need to exist for your HTML output files to work. I went with static/style.css and my js file in static/js/minimal-theme-switcher.js -- then to reference these files in my in my templates I had to use {{ get_url(path='style.css') }} and {{ get_url(path='js/minimal-theme-switcher.js') }} respectively. The templating language is clearly very powerful, but I haven't done a deep dive into using it yet. The docs are well written. Watch out for Rickrolls.
Text only blog posts can just be markdown files in the root of content. e.g. content/2025-01-13.md
Blog posts which have "accompanying" files, like images, need to be in folders along with their files. Also the file should be named index.md
e.g.
content/2025-01-13/index.md
content/2025-01-13/image1.jpg
content/2025-01-13/image2.jpg
Honestly, just clicking around my blog-src folder will probably give a decent concept of how things are structured.
Once you're ready to turn your markdown into HTML, zola build will quickly generate your output files into the folder specified in your config. That's about it. You can upload the resulting output to whatever hosting solution you wish.
The other part of this blog's tech stack is Github Pages
There's not really much to say about GH Pages that isn't already in the linked docs above. I just figured if I'm gonna use a very code centric approach to having a blog, might as well just host it (for free) from Github.
To enable comments on your blog, you can integrate Giscus, a comments widget that uses GitHub Discussions. See giscus.app for how to set it up.
Hopefully this is somewhat helpful.
P.S. bonus heart container if you get the reference in the title.