In my last post, I declared that I had killed my “About” page. It was a pragmatic decision. The page was a ghost: it rendered as raw HTML, all its links pointed to localhost:1313, and it pulled in a phantom Chinese site title that didn’t exist in my configuration.

Then, immediately after publishing that post, I discovered my “Tags” page was broken in the exact same way.

When I clicked the “Tags” link in my (perfectly functional) menu, it loaded a page that also had no CSS and contained only a giant “#Tags” title, with no actual tags listed—even though my post was correctly tagged and published.

This was the final, definitive clue.

The Unified Bug Theory

This confirmed the problem wasn’t a series of isolated glitches. It was one, single, catastrophic bug. My chosen theme, hugo-paper, had a fatal flaw.

Its “list” templates (like the homepage) worked perfectly. But its “single” template (for the About page) and its “terms” template (for the Tags page) were both fundamentally broken. They contained code that, for some reason, failed only in the Cloudflare Pages production environment, defaulting all asset paths to localhost.

My local build (hugo server -D) worked perfectly, which had masked this problem for days and led me down a debugging rabbit hole of config files, environment variables, and build flags. None of those fixes worked, because the theme’s engine itself was defective.

The Theme Transplant

The solution was obvious. You don’t fix a broken engine; you replace it.

I decided to perform a “theme transplant.” I ripped out hugo-paper completely. This involved:

  1. Running git submodule deinit and git rm to purge the old theme from my project.
  2. Choosing a new, robust, and extremely popular theme: hugo-PaperMod.
  3. Adding it as a new submodule: git submodule add ... themes/PaperMod.

Of course, this came with its own final hurdles. My brand new Hugo version (v0.150.0) immediately threw an error because the new theme’s config used a deprecated paginate key. After fixing that (it’s now [pagination].pagerSize), the Tags page still showed up empty.

One final search revealed the truth: in our quest to create a “clean” config, we had removed the block that activates taxonomies. The final piece of the puzzle was adding this back to hugo.toml:

[taxonomies]
  tag = "tags"
  category = "categories"