Taxonomy.html and terms.html reversed

I’ve been experiencing this exact issue and I believe it’s a bug in Hugo, so I filed an issue but Bjorn dismissed it as “working as designed” which is very confusing, as it seems obviously broken.

Barebones Github repo that describes how to reproduce this issue:

Unless I’m missing something, this is behaving as documented.

The template lookup order for taxonomy pages states that layouts/taxomony/terms.html (plural) takes precedence over layouts/taxomony/taxonomy.html.

The template lookup order for term pages states that layouts/taxonomy/term.html (singular) takes precedence over layouts/taxonomy/taxonomy.html.

Thanks for clearing this up. I realize that a lot of layout names stick around for historical reasons as to not break old sites, but some of the ones surrounding taxonomies are particularly confusing. Why would the layout for a taxonomy (taxonomy.html) even be in the lookup order for a term? I’ve also found it odd that the Hugo documentation presents all lookup orders as large hard to read lists all on one page, rather than showing whatever the current recommended filenames are right on the page talking about the topic. For example, on this page all it does is link to the lookup order page, not even to the section about taxonomies. If this page simply said something like “use taxonomy.html for taxonomies and term.html for terms” I think that would save a lot of hassle. I think at a bare minimum, the lookup order page should show an example content folder it might be working with and any example front matter when looking for a layout to use, as opposed to the plain text description. When I was a newcomer to Hugo this was all very confusing.

Regardless of historical context, I imagine there has to, at any given time, be a recommended standard for what to name your layouts for very standard functionality like this. It would be helpful to make that more clear for any given scenario, rather than just presenting a huge list. Debugging these kinds of issues can also be fairly annoying, as there doesn’t seem to be a Page level variable that can list “what specific layout was selected to render this page?” It would be nice to be able to just render that in a baseof.html layout as an easy way to debug layout selection. I think that the fact that there is a whole other thread on this from 3 years ago where others were confused about this exact situation and never came to this realization about layout lookup order shows that not enough is being done to clarify the links between content, configuration and layout selection.

To provide backward compatibility when building sites with v0.72.0 and earlier. See:

If you feel strongly about the documentation, please raise an issue here:

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.