On Blogging

Like many academics before me, I have spent years upholding a storied tradition: attempting to maintain a public-facing website, failing, and trying again. My initial foray into the world of personal academic websites was with the Hugo static site generator using the Academic theme. I went looking for the original Academic theme I used, and I can’t find it anywhere. There are still some screenshots of the old theme on Google Images.

My problem with Hugo was two-fold. Firstly, I didn’t understand how to really use Hugo, and I didn’t put in any effort to rectify that shortcoming. Secondly, I did not keep up-to-date with any of the developments of Hugo or the Academic theme that I was using. This meant that updates to Hugo — or the academic theme — frequently broke my website. I would apply the updated theme, and then Hugo would fail to build as I hadn’t set one of the new configuration options or additional settings.

Could I have remedied the situation by spending some time learning Hugo and how the themes worked? Absolutely. However, at the time I wanted something that just worked ™, without having to spend any time or effort. History has shown that this is not a winning strategy in any endeavour. I would routinely have to spend hours getting my site up-to-date with all of the new changes before I could even think of writing a blog post. Given how infrequently I actually worked on my website, the ratio of fixing to writing was sub-optimal to say the least.

Eventually, I got sick of that vicious cycle and gave up on writing my own blog posts. Instead, I switched to a purely static personal website that was made up of just a single index.html with a very brief biography and some social media links.

Although the above site did not look particularly aesthetically pleasing, it had the distinct advantage of minimalism. No updates would cause it to not work, and editing or adding content was extremely easy. There was no framework updating or tinkering with settings. Perhaps a version of myself born in the 80s would be appreciative of such a website. The downside was that adding additional non-homepage content — like say for example a blog — was extremely challenging, unless your idea of a good-looking blog was a loose collection of roughly related html files in the same directory. Like three honey badgers in a trench coat.

I have recently been spending most of my free time writing Rust and connecting it to R, through the excellent extendr project. Both the extendr website, and the blog are excellent examples of relatively lightweight but good looking websites. Both are built using the Zola static site generator. Zola promises that it is A fast static site generator in a single binary with everything built-in. Forget dependencies. Everything you need in one binary. After dealing with Hugo dependency hell, no dependencies sounded like music to my ears. Particularly, Zola felt like a perfect middle ground between the extreme minimalism of hand-writing your own html and using a fully defined Byzantine theme.

A Zola site is just a collection of files and folders, with a specific structure.

.
├── config.toml
├── content
│   ├── about
│   │   └── _index.md
│   ├── posts
│   │   ├── hello_world
│   │   │   └── index.md
│   │   └── _index.md
│   └── _index.md
├── sass
│   └── main.scss
├── static
│   └─ font
│      └── custom_font.woff2
└── templates
    ├── base.html
    ├── index.html
    └── post.html

What attracted me to this layout is how fiercely it aligns with my preference for ownership and predictability. Zola doesn’t abstract the machinery of a website away behind magic black boxes or deeply nested theme configurations. It offers a transparent, flat structure that says exactly what it does on the tin. If a page renders incorrectly, I don’t have to hunt through upstream GitHub theme repositories to find a breaking change; the issue can only be directly inside my own templates/ directory. It forces a certain level of intentionality that my previous Hugo setup lacked.

When you run zola build, Zola parses your Markdown files and automatically injects the text into the corresponding HTML templates. What this means is that you only have to write your core template logic once. From then on, creating a new post is straightforward, just add a new Markdown file into a folder and zola build. The source for my website can be found here https://github.com/luhann/luhann.github.io as a more detailed demonstration. What this gives me is a website that requires no external themes or dependencies — so cannot break like my previous Hugo site — but the flexibility of editing raw html for each page of my site if I so desire.

Of course, I am being entirely hypocritical here. My main problems from Hugo stemmed from using external themes, yet I tout the advantages of Zola by creating my own theme from scratch. Of course it will never break. If I had used an external Zola theme I might eventually run into the same problems as using the Hugo Academic theme. Conversely, if I had created my own Hugo theme from scratch it is unlikely I would have had any of the issues I did. What then does this mean for blogging and static site generation? Regardless of the tool you pick, spending some time upfront to learn the ins-and-outs of the tool is likely going to lead to a much less frustrating workflow in the long run. Or perhaps the true message is that one should do all they can to limit external dependencies wherever possible.