Changing and updating the brhfl dot com template

It’s been a while since we had a good meta post here, which makes for a good excuse to perform a major overhaul on my template. In seriousness, this has been a long time coming. For starters, my site wouldn’t render on versions of Hugo past 0.47.1. While not a huge deal to keep old copies around, it only becomes more work as the versions roll by. None of the changes that I’ve made to support Hugo should have any visible effect on the site. But I’ve also been meaning to play around with revamping the navigation at the top. I was using this hacked-together ‘drawer’ type system to hide and reveal the categories, archive, and et cetera sections. I have preserved an archived copy of the home page with the old template intact for demonstration purposes. But I’m not doing that anymore, and let’s start there.

Ditching the drawers

When I set out to design this blog, the drawers were an aesthetic choice that I was very happy with. Archive links by month, a long list of categories… these things were immediately available, yet hidden away. A visitor didn’t need to know that it would open like a drawer, they just needed to know that clicking ‘categories’ would get them to the categories somehow. In a lot of ways this a case of murdering my darlings, and I may revisit the drawers in the future, but for now I think this is the right way to go.

I knew from the beginning that the drawers were not ideal for accessibility. I have a ‘skip’ link in place, but if a screen-reader user did end up in the navigation section (whether by choice or not), all of those lists were still there in their entirety. The paradigm of hiding individual drawers did not carry over. And while I tried to figure out how best to fix this on several occasions, I never came up with anything suitable. While I’m sure this could have been fixed, it is no longer necessary.

Removing the drawers also removes my only dependence on JavaScript and jQuery. As of now, jQuery is only loaded when a post loads a JS file. I don’t necessarily hate jQuery as much as some folks do, but it was a dependence that was there for basically one little gimmick. Similar to the accessibility angle, the site now renders beautifully in lynx:

←←←                                                          brhfl.com (p1 of 7)
   Skip to main content

                                   brhfl.com

     * about
     * categories
     * archive
     * series
     * et cetera
     __________________________________________________________________

Changing and updating the brhfl dot com template

   bri hefele, 2019-06-25, hugo, meta

   It’s been a while since we had a good meta post here, which makes for a
   good excuse to perform a major overhaul on my template. In seriousness,
   this has been a long time coming. For starters, my site wouldn’t render

The point that really pushed me in this direction, however, was speed. Everything here is lightweight static HTML, and everything loads fast. With a 1 second open time on the drawers for aesthetic effect, the load time of a page just listing all the categories is as fast or faster. It may not be as sexy as the drawer gimmick, but moving to simple, dedicated pages is fast, functional, and allows me to play with formatting a little bit. For example, the categories drawer listed them alphabetically; I updated the categories page to have lists sorted both alphabetically and by post count. This page always existed, but you either had to know it was there or have JS disabled. It previously only had the list sorted by post count.

On the to-do list is to flesh out the et cetera page a bit more. I’ve promoted ‘series’ out of there and into the top nav itself, and have demoted my flickr page to et cetera. Not that I’m not proud of my photography or anything, but it felt a bit odd having an external link so prominently showcased. Series on this site have become a nice organizational method as well, and I’m happy to have them in the top nav.

Updating to support new Hugo versions

I occasionally regret building this thing in Hugo. The documentation is extremely hit-or-miss, the devs are quite dismissive, and they seem to live in their own little world when it comes to feature changes. The fatal error I was having was known by (at least) one of the developers to be breaking sites – it was due to a change in Go, and he raised it as an issue with that team. Yet finding any documentation on why this change affected Hugo users or how to fix it was… impossible.

The problem was that I was doing something along the lines of $value, .Page. This was never valid, it just happened to work. And that I and others somehow all came across this method of assigning variables suggests that either official documentation or tutorials once showed it. This stopped working in Go 1.11 and thus Hugo 0.48, tossing out the not-terribly-helpful fatal error: range can only initialize variables. The proper way to do this is $value := .Page, or if an index is needed, $index, $value := .Page.

Aside from that fatal error, some very useful things have been deprecated, which have been a pain to work around. For instance, this incredibly unhelpful note from the 0.55.0 changelog:

preserveTaxonomyNames configuration option is removed. Use .Page.Title.

I don’t know why URLizing (lowercasing, hyphenating, among other things) taxonomy names was ever even the default. Supposedly it was ‘by design’, but the dev links to this meaningless issue as some sort of explanation or discussion, of which it is neither. That decision was bad enough, but removing the config option to keep taxonomy names as you wrote them is patently absurd to me. So, in a ton of places like the series and category pages, I had to rewrite $taxonomy.Name to $taxonomy.Page.Title, and where I was comparing a given post’s series to the list of all series (to list all of that series’ posts in a given post’s footer), I now had to .Params.series | urlize in order to make sure it would match the absurd new format. It is entirely possible that I missed something.

I guess having everything’s name URLized does fix one of my complaints – alphabetizing was case sensitive before, so I basically had to keep all of my categories, etc., lowercase. Hack of a way to solve that, but it’s a nice side effect. I will likely go through and appropriately case my categories at some point. Also on the todo list is cleaning up a handful of warnings Hugo is throwing at me – more stuff being deprecated, huzzah.

One more accessibility note

Unrelated to template changes, but relevant for a meta post: a reader shot me an email rightfully complaining that one of my longer posts wasn’t broken up into subsections with headers. I fixed that post, and a few others as well. One nice thing about a system like Hugo is that I can just feed every raw file into wc and get a big ol’ list which I can sort to get a general idea of which of my posts are long. I know I have very small readership numbers here, but that isn’t a great excuse for letting things slip when it comes to accessibility. I’m going to try to have a better feel for the scope of posts and break them up when necessary. And of course, as mentioned, the template changes I’ve implemented should prove beneficial in an accessibility context as well.