Hello, world! Rebuilding my site with Hugo + Blowfish

TL;DR. I updated my website design.

It’s still a static site, but now generated with Hugo and its Blowfish template. The migration took one afternoon. I re-used the self-hosting setup and media assets from my previous design, freeing up time to set up something new: Webmentions. Blog post on that in progress.

I share my personal setup and the steps here. Mainly to show the very manageable effort behind this migration project. The story points. The T-shirt size. (Ok, I’ll stop.)

If you start from scratch without an existing website, there are some other prerequisites: registering your domain, setting up a server with your static site contents. Your mileage will vary.

What was wrong with the old site?

#

Until now, my home page was a beautiful, handcrafted example of how far vanilla HTML+CSS+JS can take you. A set of sliding Japanese paravents. A tiny pond with leaf-like bubbles as link containers. A credits section, dutifully listing the author of every icon and Unsplash image I had used.

The design was also woefully unoptimized for all environments that deviated from its birth conditions.

I mean it. If you did not bring a desktop computer with at least a 50Mb/s Internet connection, my website regarded you as a second-class citizen. You could brew a coffee waiting for the background images to load. And once they did… some element was always broken. Sometimes, the mobile browsers betrayed me. More often, it was Safari. I suspect they were taking turns.

Why did you do this to yourself?

#

Do not get me wrong. I loved the old design. The DIY website project taught me loads about web development, back in Corona-riddled 2020. I can recommend this experience to anyone, especially with AI powered coding assistants. The safety wheels, preventing you from falling down a debugging rabbit hole.

But now, it was time for me to learn one final lesson…

Kill your darlings

#

The decision to use Hugo came easy. I had used it for my previous blog, back then combined with the Anatole theme.

This also meant Hugo was already installed on my system. I could set up a new Hugo site quickly in the same repository as my existing website: the previous resources all resided under site, so I introduced a second directory hugo.

# Set up base directory.
mkdir hugo && cd hugo

# Let Hugo do all the work.
hugo new site . --format toml

# Okay, a little bit of work you have to do yourself.
git submodule add https://github.com/nunocoracao/blowfish.git themes/blowfish

# Should work, unless you have an issue with long file names:
hugo server

If everything flashes red because the generated file names are too long for the file system… do not panic. You need to change the fingerprintAlgorithm setting, see below.

After all this hardcore hacking, something should be alive. Exciting.

Next step was to add my profile image under hugo/assets, and mess around with the hugo.toml file until happy with the result. Here is my final template, in case you want a sneak peek of the options used:

baseURL = "https://laura.sh/"
languageCode = "en"
title = "Laura in the Machine"
theme = "blowfish"
publishDir = "../site"

[params]
  fingerprintAlgorithm = "sha256"
  colorScheme = "slate"
  defaultAppearance = "light"
  showComments = "true"

  [params.homepage]
    layout = "profile"
    showRecent = false
    # Change to layout = "background" to show homepage with image.
    # homepageImage = "..."
    # layoutBackgroundBlur = true

  [params.author]
    name = "..."
    image = "images/art/drawing.svg"
    imageQuality = 96
    headline = "..."
    bio = "..."

    links = [
      { mastodon = "..." },
      { codeberg = "..." },
      { github = "..." },
      { linkedin = "..." },
      { link = "..." }
    ]

  [[menus.main]]
    name = "About"
    pageRef = "about"
    weight = 10

  [[menus.main]]
    name = "Blog"
    pageRef = "posts"
    weight = 20

Final steps

#

Commit. Push to server. SSH login, then pull from inside server. Reload page…

…and it just worked.

On first try.

Even on mobile.

Over all these years of self-maintaining the site’s entire source code, I had already forgotten how great this can feel.