I recently became motivated to start blogging again, and needed to make some updates to my blog design before making new posts.¹ I discovered that Jekyll (the static site generator I previously used) has barely been updated in the years since I last posted. Minima, the theme I use (and the default theme for Jekyll), has been updated, but made no releases. With Jekyll essentially a dead product, I decided to follow in Julia Evan’s footsteps again and convert to Hugo.

The process of converting

Converting was actually pretty simple. Initial conversion was trivial. My blog is small enough that rather than use the importer, I just created a new skeleton and copied the content over. Then came the process of creating the theme (covered in just a bit). Lastly came the process of going through all of the content and ensuring that it reads the same. There are a few differences between the Markdown parsers that required some changes, but overall, very little needed to be done. I also managed to make a few improvements that should make editing easier in the future, such as taking advantage of Hugo’s lists and sections behavior to create proper support for series.

Creating a theme from scratch

While I like the Minima theme in general, there’ve always been a few things about it I would have liked to change. As written, however, it was a bit complicated for me and my limited CSS and web design skills. With more modern CSS capabilities, such as flexbox, grids, and nesting, I was able to make a site that I liked very simply and quickly. Not only that, but I managed to make it responsive to both size (it should work well on desktop and mobile) and color preference (light and dark).

I’m still tweaking things a little, but so far I’m pleased with the results.

Issues along the way

While the migration was pretty easy, there were some sticking points that were non-trivial:

• The <!--more--> summary separator resulted in </p><p> at the separation point. This meant my tactic of putting it right before a footnote resulted in a footnote at the start of a paragraph instead of at the end of one. Putting the footnote in front on the separator resulted in a footnote to nowhere on list pages. The solution I went with is to style footnotes with display: none on list pages.
• In Jekyll’s Markdown renderer, there is no <hr> inserted before footnotes. In Goldmark (the one used by Hugo) there is, so I needed to remove the one I’d manually added.
• While working on the style, I had a bit of trouble with the SVG image elements. It seems that SVG’s <use> element does not include definitions from external images, which meant I needed to create a way to copy gradients and styles inline into the HTML content.
• Dealing with differences in browser support for things is still a little bit of a nuisance. Specifically, the :has() selector and lh unit are missing support in Firefox, which is my default browser.
• Automatically assigning the series parameter to posts in a series without making the list page for the series part of the series tripped me up for a bit. But it turns out it’s actually pretty easy and is shown as an example in the documentation.
• Hugo does not have support for Atom feeds without making a custom output format. I’ve decided I don’t care enough to not use the default RSS feeds Hugo generates.

Results

My site does generate much faster now, and live reloading when editing is practically instantaneous. Additionally, the theme and templates I’ve managed to set up make writing and editing posts much easier and faster.

I also like that I basically understand everything that goes into how my blog looks and generates content now, since I wrote the theme myself. This also makes me more confident in my ability to support it going forward, especially as upgrading Hugo versions is just upgrading a binary.

Lastly, because everything is all in one binary instead of several Ruby gems and a runtime, I don’t have to worry about site breakages or updates causing chain reactions of going down the rabbit hole.

Future improvements

Accessibility

I’ve done the best I can with my limited knowledge to provide basic accessibility support. I have done some research into tools to help me continue to improve the level of accessibility.

Syntax Highlighting

If you’ve read the Journal, you know that I was planning to improve the syntax highlighting for Jekyll. I do think that the syntax highlighting in Jekyll was actually superior to that in Hugo, so I still intend to replace it. Unfortunately, since Hugo is not modular, this may be more difficult.

Comments

I had the idea to use ActivityPub threads² to provide a comment system for the blog. I’m not the first to have this idea, so there’s many examples I can reference, and I have a good idea of how to proceed. Comments should be coming soon.

Issues

If you run into any issues with the blog, please don’t hesitate to let me know. I’ve tested it as well as I can, but I’m certain I’ve missed stuff.³ Any issues with function, accessibility, or broken links are especially high on my list of things to track down and fix. The best way to let me know is to contact me on Mastodon.