Let hugo build the 404 page directly (#862)#1083
Open
dduugg wants to merge 1 commit into
Open
Conversation
`postdeploy` copied site/public/404/index.html over to site/public/404.html after every deploy, because netlify serves /404.html for unmatched urls and hugo was not producing it. Hugo skips its native root 404.html whenever content/404.md exists: the content page claims the route and renders to /404/index.html instead. Point the page at /404.html with `url` front matter and hugo writes it where netlify wants it, so the copy is no longer needed. Drop it, and the netlify.toml note. Also drop the theme's layouts/404.html. It has never rendered, for the same reason, so its header comment describes a mechanism that does not exist. content/404.md is the real 404 page, and is what static/admin/config.yml offers up for editing. While here: exclude the page from the sitemap, and point its two pedalpalooza links straight at their bike-summer targets rather than through a 301.
This was referenced Jul 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #862.
The build has a
postdeploystep that copies the 404 page into place after every deploy:The issue asks whether "we could do this better/easier/automatically these days." We can: the copy is unnecessary once hugo is told where to put the page.
Why the copy existed
Netlify serves
/404.htmlfor any unmatched URL. Hugo emits a root404.htmlon its own, but only when there is nocontent/404.md. Because this site has one, hugo treats it as an ordinary page, routes it to/404/index.html, and emits no root404.html. Thecpexisted to paper over that gap.The change
Point the page at
/404.htmlwithurlfront matter, and hugo writes it exactly where netlify wants it. Thepostdeploycopy and the accompanyingnetlify.tomlnote are then dead, so both are removed.Also in this PR:
layouts/404.html. It has never rendered, for the same shadowing reason, so its header comment ("this file gets overwritten by netlify.toml with 404.md") describes a mechanism that does not exist.content/404.mdis the real 404 page and is whatsite/static/admin/config.ymlexposes to the CMS for editing. Removing the template leaves exactly one 404 page.sitemap: disable: true). A "page not found" page has no business being advertised for indexing./pedalpalooza-calendar/and/pages/pedalpalooza, neither of which is a real page anymore (each survives only as a 301 to its bike-summer equivalent). Pointed them straight at the targets and updated the visible link text to "Bike Summer".Verification
Built with the same command netlify runs for production (
npm run deploycallshugo -s site), with thepostdeployhook removed, and confirmed:site/public/404.htmllands directly in the publish directory (publish = "site/public/")./404/directory is no longer generated.404references./404.htmlstill exists, which matters because_default/list.htmlhard-redirects there (<meta http-equiv="refresh" content="0; url=/404.html" />).Diffing the generated page against the previously shipped one shows only the intended link changes and nothing structural. The theme template was confirmed dead by comparing 404 output with and without it (byte-identical); note that the wider hugo build is nondeterministic (whitespace-only churn in a couple of unrelated files between runs), so the comparison was scoped to the 404 output specifically.
No backend or frontend code is touched, so there is nothing for the
apptest suite to cover.Dependency on #1080
This interacts with #1080 (add a robots.txt). That PR includes
Disallow: /404/, which matches the old/404/index.htmlpath. Since this PR moves the page to/404.html, #1080 has been updated toDisallow: /404.htmlso the rule still matches after both land. Whichever merges second, the robots.txt rule is already correct for the final state.