a hugo and archie upgrade

Yesterday I upgraded both Hugo and the Archie (it’s still being updated!) theme for this site. It’s been a couple of years since the last update, so this was a chance to tidy things up and modernize the structure. The first step was simply updating the theme submodule:

git submodule update --init --remote --merge

Then I cleared out old build artifacts so Hugo could rebuild everything cleanly. Some helpful warnings when I tried to compile hugo lead to fixing syntax on how to locate templates, conditionals, modifying some partials. Archie now compiles its own stylesheet, so my older first.css needed to be reorganized into a slimmer override layer. Social icons also changed, so I incorporated the updated Feather icon approach used by the theme.

The theme update came with several helpful warnings: renamed partials, new template locations, and a reorganized CSS pipeline. Archie now compiles its own stylesheet, so my older first.css needed to be reworked into a smaller layer of overrides. The social icons were also updated upstream using Feather. I created some new params like hideDate and showTitle.

My first pass was exploratory. I adapted partials, restored colors and spacing, and brought the layout back to its previous look. It worked—but it felt a bit stitched together.

So I took what I had learned and started over. I pulled a clean copy of Archie, went through the steps to reapply only the minimal customizations I truly needed, and rebuilt my small CSS layer on top of the new structure. The second pass was far cleaner and much easier to maintain.

In the end, doing the upgrade twice — once to learn, once to refine was the most efficient path to a solid upgrade.

Deploying with GitHub Actions

As part of the refresh, I also updated my deployment setup. I now use a small GitHub Actions workflow that builds the site on every push to master and deploys the resulting public/ directory to the gh-pages branch, seen here gh-pages.yml

name: Deploy Hugo to gh-pages

on:
  push:
    branches: [ master ]
  pull_request:

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0

      - uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.152.2'
          extended: true

      - name: Build
        run: hugo --minify

      - name: Deploy to gh-pages
        uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/master'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: gh-pages
          publish_dir: ./public

This workflow keeps the source and theme on master while publishing only the generated site to gh-pages, which GitHub Pages then serves. It’s simple, stable, and removes the need to ever commit public/ manually.

⸻