Adding Dark Mode to my Site, Shaving Yaks and Questioning my Sanity

First thing I notice when starting the local hugo server is a number of deprecation warnings, so I should probably sort them out.

Generally Hugo is excellent - it comes as one binary without dependencies (no Python venv, no minor galaxy of NPM dependencies), has lots of cheap/free hosting solutions available and it is super fast; especially in the local preview server.

My biggest irritation with Hugo is the speed of releases combined with a lack of semantic versioning. This means it's hard to know if there might be breaking changes between the version you last used, the newest version and the version that your hosted static site build step might be using. On my laptop (running FreeBSD 14.1 RELEASE) I have Hugo v0.135.0+extended installed, which is pretty recent (September 2024) and so should be widely available and supported (wait, was that a distant train I heard, or an ominous noise?).

So I remove the use of .Site.Social parameters in the templates, as this is deprecated as of version v0.124, and rename them in the config.toml site configuration file to .Params.Social (+1🐃). Talking of configuration files, as of version v0.109 it should be renamed to hugo.toml (+1🐃), which is not deprecated yet, but many happen at some random version in the future. These updates need to happen both in the theme, and its example site, but also on the configuration file of my actual site.

I did this first because it requires the least understanding of all the template code, I just have to add some new lines into the head.html template partial. The only social media I currently use is Mastodon, and it's nice to see the little preview cards appear for linked pages and articles, so I wanted to add that to my site. Jeff Sikes has a good explanation of how they work, and Robb Knight has the excellent Lens page that allows you to check to see if your site is working, and gives you some helpful examples.

Adding these in is pretty easy. There are two stumbling blocks. First I have to create some kind of default preview image for the site, that's not used when linking to an blog post that has a 'featured image'³ - so after some messing around in Inkscape I come up with this image, that I would politely describe as 'cheap inspirational poster' in appearance:

Apart from the image and name, another important property that the preview shows is a description of the site, and I don't have one other than "Henry Leach's personal blog", which is as bland as it is useless. It should be something short, descriptive and probably biographical. Failing that, something to give you a 'vibe' of what to expect.

These are hard questions: Who am I? what do I want people to think about me? What should people expect?

I have no idea; looking at the tags it covers everything from music, travel, guitar, computer stuff, and some web design things like this. I'm not trying to sell anything, or build a brand - so there's no common thread to cling to, just my shifting chaos of interests. I try and invent a few tag lines, that perhaps hint more at personality than content:

• Bad Ideas, Badly Written
• The World is Confusing, This Won't Help
• Ideas Not Worth Sharing

All of these sound like sarcastic mission statements, which I guess is a personality? but it doesn't sound like a good personality, plus I dont' think they sound like me. After much deliberation I stick with "Henry Leach's personal blog"; which is at least true if not helpful. +1🐃 for a minor existential crisis that led nowhere.

Adding the Mastodon author attribution is super quick, and adding the domain to my Mastodon profile is also easy. All killer, no filler. Zero yaks here.

Job done, right? Well, the Lens website also shows other metadata I currently don't have, and hadn't thought about, specifically theme-color and apple-touch-icon. So I add those as well, even though I own no Apple device less than a decade old, and don't use this info, +1🐃.

Lastly, I'm getting self conscious of my lowly little favicon icon, it's fine - it works, and doesn't need touching…but apparently the cool kids are all using SVGs these days, which is better for high resolution screens. I wouldn't want to look pixely now, would I? That's an unnecessary change, but quick, as I already have the SVG I used to create the little 'HL' glyph that is the current favicon, so another few minutes in Inkscape to neaten that up means I can just drop it straight in. +1🐃.

Now, to the (dark) heart of the matter. There a few ways to create a dark mode, and a web search will give you many options, but less is more and this great CSS-Tricks article shows how you can use color-scheme to give light and dark options that are selected by the browser, based on the user's preferences. Combined with using variables and the new light-dark option (available on all major browsers as of 2024⁴).

Implementing both light and dark modes becomes as simple as adding the following to the top of your style sheet, and then using the colour variables where you need to define colours.

:root {
    --bgColour: light-dark(#f9fafb, #404040);
    --bgContrastColour: light-dark(#f2f2f2,#757575);

    --textMainColour: light-dark(#404040, #f9fafb);
    --textLightColour: light-dark(#757575, #f2f2f2);

    --baseAccentColour: #004d87;
    --highLightColour1: #5badf0;
    --highLightColour2: #ff8263;
    --highLightColour3: #00bea2;

    color-scheme: light dark;
}

body {
    font-size: medium;
    font-family: Georgia, serif;
    color: var(--mainTextColour);
    line-height: 1.75;
    letter-spacing: 0.008em;
    background-color: var(--bgColour);
}
/* etc */

and that's it!

You could make things more complicated, as explained in the above CSS-Tricks article, by adding button to allow users to switch and potentially using cookies to save the preference between pages and visits. I think that makes sense if you have lots of colours, or the light/dark options are more colourful than just light and dark - but I'm keeping it simple. I'm going to assume that people set the browsers to be what they want to see, and then respect that. It also makes the site much simpler, and doesn't get into the weird territory of me setting up something that saves data on someone else's computer, which seems a little rude without asking.

So we're done…

My site isn't very large, either in page count, or per page size, but I like to support the idea that web pages should be as small as possible. This uses fewer resources and they become more accessible for users with slower connections. I may have a small obsession with this topic. It is possible to take this idea too far, so let's first remember the wise words of Donald Knuth:

"The real problem is that programmers have spent far too much time worrying about efficiency in the wrong places and at the wrong times; premature optimization is the root of all evil (or at least most of it) in programming."

…and now do some premature optimisation for my ten regular visitors.

Before making change, let's get a baseline result, using the Debug Bear Speed Test. There are a lot of stats, but the ones I'm most interested in are (using Mobile and location US East):

• Page Weight (the amount of data that needs to be downloaded): 494 kB
• CPU Time (amount of CPU compute time required to render the page): 299 ms
• Cumulative Layout Shift (how much the page shifts around as parts get loaded in): 0.08

There are other measures as well, but they are heavily dependent on the network connection and other traffic at the time, and tend to fluctuate a little by themselves. Debug Bear has some good explanations if you want to dive deeper, like explaining what the Cumulative Layout Shift measure is; but lower is better.

One improvement I've wanted to make for a while is switching the images to the WebP format. These are mostly smaller than JPG or PNGs - so the pages load a little faster. I've put it off because for a long time I was still using Safari on my 2013 MacBook Pro, which is stuck on MacOS Catalina (10.15) and so is Safari 15, which doesn't support WebP. Why the version of the browser is linked to the OS is something I don't understand⁹. WebP has been supported by all modern browsers for quite a long time now (since 2014 by Chrome, and 2019 for Firefox, and today even by the minimal browser Links2), so it's probably safe to make the change.

Getting Hugo (extended version) to convert images isn't too hard, there's a built in imaging processing capability which allows you to manipulate images from your page templates, by setting the target format to be WebP. Thanks to this forum post by one of the Hugo maintainers, there's a template code snippet you can add to the theme file layouts/_default/_markup/render-image.html that will convert all images added to markdown pages to convert them to WebP.

{{- $u := urls.Parse .Destination -}}
{{- $src := $u.String -}}
{{- if not $u.IsAbs -}}
  {{- $path := strings.TrimPrefix "./" $u.Path }}
  {{- with or (.PageInner.Resources.Get $path) (resources.Get $path) -}}
    {{- with .Process "webp" -}}
      {{- $src = .RelPermalink -}}
      {{- with $u.RawQuery -}}
        {{- $src = printf "%s?%s" $src . -}}
      {{- end -}}
      {{- with $u.Fragment -}}
        {{- $src = printf "%s#%s" $src . -}}
      {{- end -}}
    {{- end -}}
  {{- end -}}
{{- end -}}
{{- $attributes := merge .Attributes (dict "alt" .Text "src" $src "title" (.Title | transform.HTMLEscape)) -}}
<img
  {{- range $k, $v := $attributes -}}
    {{- if $v -}}
      {{- printf " %s=%q" $k $v | safeHTMLAttr -}}
    {{- end -}}
  {{- end -}}>
{{- /**/ -}}

That's good for the post pages, but the index page doesn't use that template. Here I can just add the webp target format in, and voila, it works.

What doesn't work, irritatingly, is pages generated by org-mode, which I prefer to markdown. I'm not 100% sure what the pipeline is, but I understand it uses go-org to generate the HTML from org-mode files, and not the markdown parser, and I don't know how to intercept that without perhaps manually converting the images to WebP first? That's a future yak. For now it means that if you look at an older post with images that I wrote in markdown, like this one, then the images are WebP, but if you look at one written as org-mode the images will be in their original format.

Having individual pages load a little slower is perhaps annoying, but it's the index page that most people will notice most.

While working on the images on the front page the other improvement we can make is to stop the layout shift. This happens when the browser doesn't know the dimensions of the image when it loads the page below it, and then once the image has appeared, the link you were going to click is now somewhere else. On a lot of pages that happens with adverts, and it's really annoying. You can solve this by putting the image dimensions into the <img> tags via the width and height properties, that Hugo can pre-fill from the image's properties, then the browser will reserve the right amount of space for the image to load into.

The last recommendation from DebugBear is to add lazy loading to the images that don't appear on the first screen of a webpage. On my index page not all posts have a featured image, but if does and it's not the first post then it'll add the loading="lazy" property to the image tag. In most cases that'll be enough to make sure most images are rendered once the rest of the page is done.

Right, what has all this tweaking got us? Re-running the test on the same page once the changes were deployed showed:

The page already started from a good position by virtue of being simple, but that looks like some good premature optimisation. The CPU time has almost halved, and thanks to the lazy loading the WebP images, the page size is one tenth of what is was. That success without detours does mean no yaks to be shaved here, unlike…

With all my changes complete, I merge the changes into the main branch of my website's code, push that to the Git repository, put my feet up and wait for the updated page to go live. Except I get an email from Render telling me I've got a deploy failure, and my published site remains stubbornly in light mode.

The build logs seem to show it can't find a config.toml file, which makes sense, we renamed it to hugo.toml to match the more recent versions…of…Hugo…wait, what version is Render using? 0.124 - which is from early 2023. In Hugo terms that's ancient, the version on my laptop is 0.135, and they just released 0.140.

Render doesn't have a built-in way to specify the Hugo version. I check my Netlify account, which does have a way of specifying the version - useful since Netlify's default version appears to be Hugo 0.85, a version released shortly before Queen Victoria was coronated. But I don't want to suddenly have to re-organise my website, DNS records etc. to work with Netlify; for the sake of dark mode.

Luckily others have had this problem before me and shared their solution, which is to write a shell script that downloads and installs the correct Hugo version during the build step in the Render container, but pointing the buildCommand setting at a script. This is the variation I settled on, based on the two examples given in the forum thread:

#!/bin/sh

HUGO_VERSION="0.135.0"

TAR_NAME="hugo_extended_${HUGO_VERSION}_Linux-64bit.tar.gz"

echo "old: " "$(hugo version)" # Output the OLD version

if [ ! -f "$XDG_CACHE_HOME"/hugo ]; then 
  echo "...Downloading HUGO" 
  mkdir -p ~/tmp 
  wget -P ~/tmp https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/${TAR_NAME} 
  cd ~/tmp || exit
  echo "...Extracting HUGO" 
  tar -xzvf ${TAR_NAME}
  echo "...Moving HUGO"
  mv hugo "$XDG_CACHE_HOME"/hugo  
  cd "$HOME"/project/src || exit # Make sure we return to where we were
else 
  echo "...Using HUGO from build cache"
fi

"$XDG_CACHE_HOME"/hugo --gc --minify

I then include this as render-deploy.sh in the website's git repository, and can then call it when building. It also means I can easily keep the deployment version of Hugo in sync with the one on my computer, and hopefully not have any further unpleasant build surprises. +1🐃 for having to reconfigure most of the deployment process.

According to grep -o '+1🐃' index.org | wc -l I've gathered 12 Yak shaving experience points during this little dark mode adventure. That seems like a lot for something as trivial as dark mode, which I, as the main reader of my own site, don't even use on sites with lots of text¹⁰.

So why bother? Well perhaps it's useful to someone somewhere, which is one of the key reasons why I keep a blog at all. Also curiosity, I want to know how others sites do it, how to generate the social graph previews, and what can be done to reduce website bloat. Having your own site to tinker with is a good way of learning how different parts of the web work; if you're that way inclined - even though you could just read how, and not do it.

They're reasons, but not, I think, the real reason, which is that it's nice to have the satisfaction of having completed a little something to a standard you're happy with. At work, and at home, often other pressures mean you can't finish off all the details you want; something works - but time means you have to move on. On private projects you get to decide when it's done, and can do the work to a standard you're happy with. Perhaps that means tinkering to an unreasonable extent, perhaps that means throwing something together as quickly as possible and calling it done. Doesn't matter: you decide. That agency is what makes it more fun to work on, because you get to keep going until you're happy.