Wherever Hugo, there you are

At long last, I have finished migrating my personal site from Jekyll to Hugo.

The site has been a static site in the sense of no content updates for too long. The last post I published on this site was in 2021.¹ It was an outdated, heavily customized Jekyll site with a theme that included a grunt.js build for the frontend part of the site (compiling and minifying Javascript and SCSS, I think). I stopped posting because I wasn’t confident the site would still build and publish without errors, and I didn’t want to break it (that would make fixing it more urgent!). The site was also getting slower to build because I had accumulated a decent amount of content, exacerbated by an experiment with microblogging.

I’m a big fan of Hugo. It’s a fast, powerful static site generator written in Go with a lot of features built-in. Hugo is what we used to build Startwords, an experimental research journal from the Center for Digital Humanities at Princeton, first published in 2020. I’ve used it for a team reporting site where I took significant advantage of the data integration capabilities. I helped convince the other DHTech steering committee members to use it for the DHTech site when that site needed an update. I’ve done some other experiments with it too. It’s often our own projects that come last, right?

In theory, migrating from Jekyll to Hugo shouldn’t be that hard. They’re both static site generators, they both use Markdown content pages with yaml metadata, the files and templates are structured in similar ways, etc. There are existing utilities to convert a Jekyll site to a Hugo site (Hugo even includes a built-in import jekyll command), because I’m not the first one to go down this path. But in actuality, my personal site has been a place where I tinker and experiment. Over time, I added and adapted features and customizations that I found elsewhere or invented myself out of necessity or possibility. I didn’t keep track of how I customize and changed my theme or site styles or hacked in; I was usually just trying to get something to work in the short-term and not thinking about maintenance. In the end, I found an existing python script for migrating content that I was able to iteratively customize to handle the quirks in my content.

Here are some of the ways I’ve customized my site: custom figure templates with captions and alt text (this required customization in Jekyll); posts with multiple authors (e.g., this post with content from a 2016 Open Repositories poster, one post authored by someone else (this news post I migrated with other content for vanity reasons, one post where I’m not technically the first author (a repost of a 2012 DH poster proposal with Brian Croxall; I decided to let the order author go in the new version (sorry, Brian); posts originally published elsewhere, or cross-published on other sites; custom javascript, e.g. to embed a chart; custom styles, e.g. for a gallery of images (this 2013 dbpedia experiment); markdown in post titles (a post of my 2019 talk, “Best Practices?”); webmentions integration. Many of these things now have built-in support in the Hugo theme I’m using. For a while I was experimented with a microblogging section that I syndicated to twitter, an approach that comes from the IndieWeb community: Publish (on your) Own Site, Syndicate Elsewhere (POSSE). The fracture of the social media scene after the changes at Twitter made it easier for me to let that part go and drop it in the migration (maybe I’ll come back to it later). Hugo is so fast that the amount of content wouldn’t be a technical problem; it was all the work of customizing and testing and making decisions.

The migration was slow because I was doing it on the side in smaller bits of time, but also because maintenance and migration often doesn’t feel that exciting. At some point early on in the process I got sidetracked wih ideas of using CSS shapes and making a custom theme. A colleague wisely pointed out how much unnecessary work that would be, and that I should use an existing theme and focus on the content migration first. Then I started working with the default Ananke theme; it’s perfectly serviceable, but not very exciting. I didn’t recognize until later on that working with a theme I found boring made me less excited about working on the new version of my site. At some point, I looked again at the long list of Hugo themes and found a couple of themes I was excited about. Eventually I settled on Blowfish, which seems to be getting more and more popular and has improved since noticeably since I first started working with it.²

The migration was 90% complete but I got stuck for a while. The last major thing I needed to handle was Webmentions, which I didn’t want to give up on like I did with the microblogging experiment. Webmentions is an open standard for notification of distributed interactions (comments, likes, reposts, links) on the web, allowing for peer-to-peer interactions not limited to a single silo like a social media platform. My setup is powered by Webmention.io and Bridgy. I used this setup before when I was experimenting with posting short updates on my own site and syndicating to twitter. When I was finally ready to work on it to complete the migration, I found that I was able to build on my previous work (good job, past self!). I had an existing python script to pull my mentions data as JSON and split it out into files based on the section of my site. Previously I’d been displaying mention information with some custom JavaScript, but I prefer things to work even if JavaScript is disabled, so I wrote a custom Hugo template partial to load, filter, and display the site data. You’ll see it at the bottom of some posts that I’ve shared on social media. Once I’m happy with this site (or get bored with working on it), maybe I’ll circle back to my experiments with syndicated microblogging.

I’m still customizing the theme a lot because some of the changes I need aren’t easy to add in the configurable or extensible places, and I have a long list of things I want to add, or tweak, or improve. I’ll probably try to do better with tracking my changes and customizations now, at least for a while. (I’m using private GitHub Projects; I had a project to keep track of the tasks to finish the migratiom to Hugo, and I started a new one so I can keep track of - and prioritize! - the updates I want to do.) The thing is, now I’m excited about this site again. Now that I’ve finally gotten over the hurdle and made the switch, it’s easy to work with again: easy to add new or cross-posted content, and easy to customize. I’m looking forward to writing and tinkering more.