Website redesign

One of the things which drew me to Hugo was the quality of the available themes. I started with Hermit. However, Hugo moves at a rather rapid pace, and my page with the now-unmaintained theme stopped building at some point ². There is a maintained fork, Hermit - V2, but it isn't fully plug-and-play (some configuration options are changed). This encouraged me to look further and consider a redesign…

For something as "simple" (in its purpose) as a static site generator, Hugo does evolve at speed. I found out that the recommended way of installing themes is now through Hugo modules, which seem to be a wrapper for Git submodules combined with Go package / dependency management (don't quote me on this, I only gave the docs a cursory read). Thankfully, plain Git submodules still work (and so does symlinking).

Unfortunately, I feel that there is some bloat in the theming space. Some themes require an additional installation of JavaScript libraries with npm, some ship with rather heavy assets – which is not what I want. Although, in fairness, there are also many which boast minimalism.

One of the themes which caught my eye was risotto. Terminal aesthetics, plain HTML + CSS, and a really nice system of built-in base16 color schemes are its definite strong points in my eyes. It became my chosen theme for a few weeks.

There were, however, a few things which I didn't fully enjoy, like the lack of extra line spacing under headings. I looked under the hood and the theme seemed nicely tweakable, but instead of making tweaks it seemed more fun to try and start from scratch…

I had been thinking about writing my own Hugo theme from scratch, and while making all the changes above the time seemed better than ever. I wanted to be able to control typography and color scheme, and I also wanted to take a closer look at Hugo internals. Thankfully, Hugo docs are rather good, and I was able to hack together something which met my vision:

• Restrained design.
• Catppuccin colors.
• Vollkorn (serif), Anonymous Pro (monospace) fonts.
• Minimal technology: pure HTML + (s)CSS, no JavaScript.
• Self-hosting: fonts and icons are bundled (OFL / CC-BY / MIT license), no CDNs and Google Fonts.
• Works-for-me project: not covering all of Hugo possibilities.

I do not have a repository to share since I am currently rethinking my relationship with GitHub (The world’s leading AI-powered developer platform), but I will try to remember to update the post with a link when I settle on something.

Another thing which I really like about Hugo is that it supports Org mode out of the box. Well, mostly. It has worked for me for a long time and still does, but recently I ran into a few limitations.

While Org mode is well documented, its reference implementation is in Emacs Lisp. Hugo does not implement its own parser; instead, it relies on a third-party library go-org, which aims to implement a subset of Org mode according to the 80/20 rule, and is not being particularly tailored for Hugo (which is a perfectly reasonable approach from its developer).

This meant, however, that on one unlucky day I discovered two unsupported features. First, it is not possible to toggle line numbers for a code block, as switches are not interpreted (Org native example, with starting line number set: #+BEGIN_SRC emacs-lisp -n 20). Second, .webp images were not being recognized as such (images are inserted as regular links, and the parser decides what to do with them based on file extensions). The latter has now been fixed.

Interestingly, there is Org-hugo, an Emacs package providing an export backend which translates Org to Hugo Markdown. However, going Org → Markdown → HTML seems like an overly complicated process (at least when compared to just calling Hugo).

To be clear, I consider these limitations minor, and I will continue using Org mode with Hugo, but learning about these limitations was interesting.

While exploring the topic, I was reminded how good the plain Org HTML export (C-c C-e h h) looks, with its black-on-white, 60 em wide, nicely spaced content. It can also provide code block syntax coloring, but the default behaviour is to use colors from the Emacs theme – which looks terrible when using a dark editor theme and keeping the default white HTML background.

The CSS markup is documented, so I believe it should be possible to style the output at will (I also found at least one alternate stylesheet), but that seems like a bit of work. I had a brief look, but the code blocks seemed to be the biggest obstacle (I think it is either theme colors, or external processors ³).

And even if I could see myself exporting each page manually (my website is simple after all), Hugo does bring more features on top. Generating a list of posts is the obvious one, but Hugo also generates lists of tags with its taxonomies feature. Really neat, and it requires very little work to template for.

The list of Org-specific site generators is sadly filled with "unmaintained". The most interesting project is probably lazyblorg (generator behind https://karl-voit.at/ which I already linked to in one of the footnotes), but it seems to be tailored to a workflow slightly different than mine.

Finally, I came upon hakyll, written in Haskell (that would make for a double niche combination), interesting in that it delegates format conversion to pandoc ("write your content in whatever format you prefer"). Pandoc is solid, but I was always a bit hesitant to go into pandoc templating.

Interesting possibilities, but I will be staying with Hugo for a while now – changing a framework could be a fun exercise, but not a small one.