sneak/lora.vegas
1
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects Releases Wiki Activity

Eliminate the Hugo taxonomy layout warning by disabling unused page kinds #13

New Issue
Closed
opened 2026-08-09 03:43:16 +02:00 by clawbot · 2 comments
clawbot commented 2026-08-09 03:43:16 +02:00
Collaborator
Copy Link
Copy Source

Problem

Every build of this site emits:

WARN  found no layout file for "html" for kind "taxonomy": You should create a
template file which matches Hugo Layouts Lookup Rules for this combination.

Reproduce with make test or script/cibuild.

Hugo enables the tags and categories taxonomies by default. This site is a
single page with no taxonomy terms and no taxonomy templates, so Hugo generates
taxonomy list pages it has no layout for and warns on each build.

Two reasons to fix it rather than live with it:

  1. A permanently-warning build trains everyone to ignore build warnings. The
    next warning — a real one, about a broken link or a template error that has
    not yet become fatal — will scroll past unnoticed. #9 is about to route
    script/lint into the gate, which adds --printPathWarnings output to the
    same stream; the noise floor should be zero before that lands.
  2. Hugo is emitting output pages nobody asked for.

Fix

Disable the unused kinds in hugo.toml:

disableKinds = ['taxonomy', 'term']

This is the documented Hugo mechanism for a site that uses no taxonomies. It
removes the warning at its source rather than suppressing it.

Definition of done

  1. hugo.toml disables the taxonomy and term kinds.
  2. make test and make lint both produce zero WARN lines. Paste the
    full build output into the PR to demonstrate it.
  3. The rendered site is unchanged: build public/ before and after and confirm
    index.html and css/style.css are byte-identical. Only the (unused,
    unlinked) taxonomy pages should disappear from public/.
  4. Hugo's generated sitemap.xml still contains the home page and no longer
    references taxonomy URLs. Confirm the sitemap is still generated at all — if
    disabling these kinds also drops the sitemap, revert and use a narrower fix.
  5. make check passes and script/cibuild succeeds.
  6. TODO.md updated in the same commit.

Explicitly out of scope

  • Do not add --panicOnWarning or otherwise make warnings fatal. That is a
    separate policy decision about how strict the gate should be, and it would
    need to be made deliberately rather than as a side effect of this cleanup.
  • Do not create empty taxonomy templates to satisfy the lookup. That adds
    dead files to silence a warning about pages the site does not want.

Relationship to other issues

Independent of #9, but they touch the same build output. Whichever lands
second should re-verify the combined output is clean.

## Problem Every build of this site emits: ``` WARN found no layout file for "html" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination. ``` Reproduce with `make test` or `script/cibuild`. Hugo enables the `tags` and `categories` taxonomies by default. This site is a single page with no taxonomy terms and no taxonomy templates, so Hugo generates taxonomy list pages it has no layout for and warns on each build. Two reasons to fix it rather than live with it: 1. A permanently-warning build trains everyone to ignore build warnings. The next warning — a real one, about a broken link or a template error that has not yet become fatal — will scroll past unnoticed. #9 is about to route `script/lint` into the gate, which adds `--printPathWarnings` output to the same stream; the noise floor should be zero before that lands. 2. Hugo is emitting output pages nobody asked for. ## Fix Disable the unused kinds in `hugo.toml`: ```toml disableKinds = ['taxonomy', 'term'] ``` This is the documented Hugo mechanism for a site that uses no taxonomies. It removes the warning at its source rather than suppressing it. ## Definition of done 1. `hugo.toml` disables the `taxonomy` and `term` kinds. 2. `make test` and `make lint` both produce **zero** `WARN` lines. Paste the full build output into the PR to demonstrate it. 3. The rendered site is unchanged: build `public/` before and after and confirm `index.html` and `css/style.css` are byte-identical. Only the (unused, unlinked) taxonomy pages should disappear from `public/`. 4. Hugo's generated `sitemap.xml` still contains the home page and no longer references taxonomy URLs. Confirm the sitemap is still generated at all — if disabling these kinds also drops the sitemap, revert and use a narrower fix. 5. `make check` passes and `script/cibuild` succeeds. 6. `TODO.md` updated in the same commit. ## Explicitly out of scope - Do **not** add `--panicOnWarning` or otherwise make warnings fatal. That is a separate policy decision about how strict the gate should be, and it would need to be made deliberately rather than as a side effect of this cleanup. - Do **not** create empty taxonomy templates to satisfy the lookup. That adds dead files to silence a warning about pages the site does not want. ## Relationship to other issues Independent of #9, but they touch the same build output. Whichever lands second should re-verify the combined output is clean.
clawbot commented 2026-08-09 17:31:23 +02:00
Author
Collaborator
Copy Link
Copy Source

Implementation plan

First, re-verified the premise against current main (9e3f955), since the
build now runs the pinned, hash-verified hugo v0.164.0 from script/bootstrap
rather than the apk 0.139.0 that was current when this issue was written. The
warning is unchanged on v0.164.0:

WARN  found no layout file for "html" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

and the generated sitemap still lists the two unwanted taxonomy URLs alongside
the home page:

https://lora.vegas/categories/
https://lora.vegas/
https://lora.vegas/tags/

So the issue is current and disableKinds is still the documented mechanism on
this version.

Change

One line in hugo.toml:

disableKinds = ['taxonomy', 'term']

Nothing else. No taxonomy templates, no --panicOnWarning, no changes to
script/bootstrap or .gitea/workflows/deploy.yml — the live deploy path is
untouched by this.

Verification

  1. public/ built before and after; index.html and css/style.css compared
    byte-for-byte, and the full file list diffed so the only deltas are the
    disappearing categories/index.xml and tags/index.xml.
  2. sitemap.xml confirmed still generated, still containing the home page, and
    no longer containing any taxonomy URL. If it vanishes, revert and use a
    narrower fix rather than shipping a sitemap-less site.
  3. make test and make lint output scanned for any remaining WARN line;
    target is zero.
  4. make check green, then script/cibuild, with the make check layer
    confirmed to have genuinely executed rather than being served from cache
    (#23 is still open, so exit 0 alone is not evidence). Cache invalidation
    will be scoped to this build only — no builder prune, since this is a
    shared host.
  5. TODO.md updated in the same commit.
## Implementation plan First, re-verified the premise against current `main` (`9e3f955`), since the build now runs the pinned, hash-verified hugo `v0.164.0` from `script/bootstrap` rather than the apk 0.139.0 that was current when this issue was written. The warning is unchanged on `v0.164.0`: ``` WARN found no layout file for "html" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination. ``` and the generated sitemap still lists the two unwanted taxonomy URLs alongside the home page: ``` https://lora.vegas/categories/ https://lora.vegas/ https://lora.vegas/tags/ ``` So the issue is current and `disableKinds` is still the documented mechanism on this version. ### Change One line in `hugo.toml`: ```toml disableKinds = ['taxonomy', 'term'] ``` Nothing else. No taxonomy templates, no `--panicOnWarning`, no changes to `script/bootstrap` or `.gitea/workflows/deploy.yml` — the live deploy path is untouched by this. ### Verification 1. `public/` built before and after; `index.html` and `css/style.css` compared byte-for-byte, and the full file list diffed so the only deltas are the disappearing `categories/index.xml` and `tags/index.xml`. 2. `sitemap.xml` confirmed still generated, still containing the home page, and no longer containing any taxonomy URL. If it vanishes, revert and use a narrower fix rather than shipping a sitemap-less site. 3. `make test` and `make lint` output scanned for any remaining `WARN` line; target is zero. 4. `make check` green, then `script/cibuild`, with the `make check` layer confirmed to have genuinely executed rather than being served from cache (#23 is still open, so exit 0 alone is not evidence). Cache invalidation will be scoped to this build only — no builder prune, since this is a shared host. 5. `TODO.md` updated in the same commit.
clawbot commented 2026-08-09 17:33:34 +02:00
Author
Collaborator
Copy Link
Copy Source

Implemented in #29 (commit 70048b3).

hugo.toml gains disableKinds = ['taxonomy', 'term'] with a comment
explaining why; TODO.md updated in the same commit. No taxonomy templates
added, no --panicOnWarning, nothing else touched.

Against the definition of done:

  1. Done.
  2. make test, make lint and the full make check all emit zero WARN
    lines. The build output is now just the hugo banner and the page count
    table.
  3. public/ diffed before and after with diff -r. index.html,
    css/style.css and the RSS index.xml are byte-identical. The only
    deltas are the intended ones: categories/index.xml and tags/index.xml
    are gone, and sitemap.xml is trimmed.
  4. sitemap.xml is still generated and still contains the home page — the
    revert condition does not trigger. It went from
    https://lora.vegas/categories/, https://lora.vegas/,
    https://lora.vegas/tags/ down to just https://lora.vegas/.
  5. make check passes. script/cibuild succeeds, and the RUN make check
    layer was confirmed to have genuinely executed rather than being served
    from cache: with plain progress output it reported DONE 4.6s with its
    full build output present, not CACHED, on the container's own pinned
    hugo v0.164.0. No builder prune was used.
  6. Done.

Worth recording for whoever picks up
#25: with this merged the noise
floor is actually zero, so making warnings fatal is now a viable decision
rather than one that would immediately fail the build.

script/bootstrap and .gitea/workflows/deploy.yml are untouched, so the live
deploy path is unaffected. Not verified: an actual Cloudflare Pages deploy,
which only happens on merge to main.

Implemented in https://git.eeqj.de/sneak/lora.vegas/pulls/29 (commit `70048b3`). `hugo.toml` gains `disableKinds = ['taxonomy', 'term']` with a comment explaining why; `TODO.md` updated in the same commit. No taxonomy templates added, no `--panicOnWarning`, nothing else touched. Against the definition of done: 1. Done. 2. `make test`, `make lint` and the full `make check` all emit zero `WARN` lines. The build output is now just the hugo banner and the page count table. 3. `public/` diffed before and after with `diff -r`. `index.html`, `css/style.css` and the RSS `index.xml` are byte-identical. The only deltas are the intended ones: `categories/index.xml` and `tags/index.xml` are gone, and `sitemap.xml` is trimmed. 4. `sitemap.xml` is still generated and still contains the home page — the revert condition does not trigger. It went from `https://lora.vegas/categories/`, `https://lora.vegas/`, `https://lora.vegas/tags/` down to just `https://lora.vegas/`. 5. `make check` passes. `script/cibuild` succeeds, and the `RUN make check` layer was confirmed to have genuinely executed rather than being served from cache: with plain progress output it reported `DONE 4.6s` with its full build output present, not `CACHED`, on the container's own pinned hugo v0.164.0. No builder prune was used. 6. Done. Worth recording for whoever picks up https://git.eeqj.de/sneak/lora.vegas/issues/25: with this merged the noise floor is actually zero, so making warnings fatal is now a viable decision rather than one that would immediately fail the build. `script/bootstrap` and `.gitea/workflows/deploy.yml` are untouched, so the live deploy path is unaffected. Not verified: an actual Cloudflare Pages deploy, which only happens on merge to `main`.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bot
Agent's turn to work
 merge-ready
Review passed; ready to merge
 needs-checks
PR awaiting green checks
 needs-rebase
PR needs rebase onto main
 needs-review
PR awaiting adversarial review
 needs-rework
Review failed; PR needs rework
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
clawbot sneak (Jeffrey Paul)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/lora.vegas#13