This site uses Hugo to generate all its web page content. About a year ago, Hugo introduced a more streamlined approach to how it handles templates. A couple of my custom pages broke as a result. Here is how I fixed them.

Until recently I was using the following version of Hugo:

• v0.134.1 (released September 2024)

The other day I upgraded to the following version:

• v0.157.0 (released February 2026)

In between these two versions, there was the following major release, affecting how templates are structured:

• v0.146.0 (released April 2025 - release notes)

Many of the template changes are backwards-compatible with what I previously had - but just for the record, I followed the instructions here to bring my layouts/ folder up-to-date. Mainly this involved performing the file moves and directory renames mentioned on that page.

That just left my “about” and “search” pages, which were still not working after the above changes. Each page has a custom HTML layout and a related Markdown file:

• layouts/page/about.html and content/about.md
• layouts/page/search.html and content/search.md

The fix for these was straightforward:

Step 1: I renamed the page/ directory to custom/ because any directory under layouts/ not starting with a _ now represents the root of a page path.

To put this another way, we can now refer to the custom/ directory as the name of a page type (see step 2 below). And custom is a more meaningful name than the previous (generic) page.

Step 2: In each Markdown file, I added the following to the file’s front matter (in TOML, in my case):

In about.md:

1
2

type = 'custom'
layout = 'about'

In search.md:

1
2

type = 'custom'
layout = 'search'

That type = 'custom' tells Hugo to look in my newly renamed layouts/custom directory for a template. See type.

And layout = 'whatever' tells Hugo to specifically use the whatever.html template. See layout.

That’s it! All fixed.