Automatically handling empty/non-existing taxonomy entries

Hi everyone! I have my personal website on Hugo, I love it, and am trying to step it up a bit.

For my question, I went through the related documentation, some google-fu and a bunch of queries here at the discourse (e.g. Search results for 'empty taxonomy page' - HUGO) and couldn’t find any related question. Please excuse me if this is answered somewhere else, I’ll be glad to read any related information.

Now to my question:

Imagine that I am creating a web with tags and categories, and also other people will be filling it with content. But I want the homepage to already include a hyperlink to e.g. “Publications” like this: Obviously, if there aren’t any entries with that tag, when clicking on that link, the server will throw a 404 error. I would like to handle these cases automatically (e.g. by showing an “empty” list page).

My question is: what is the best way to deal with this? I would very much like to take advantage of the built-in taxonomy system, to expose filtered contents via such links, because this is easy to understand for anyone (not only myself). And I would dislike the idea of having to provide the website with “dummy” entries that have all possible tags and must be deleted at some point (too brittle for my taste).

The only idea that comes to my mind is conditional routing on the 404, but 1. I don’t know how to do that and 2. Maybe there’s a better way.

Sorry for not providing a MWE, this is more of a design question, hope that’s OK!

Best regards,

I don’t think Hugo provides a way to render a page for a taxonomy term that isn’t used. In Hugo’s view the term doesn’t exist on the site.

Additionally, I can’t think of way to intelligently create a page where a missing taxonomy term page should have been (assuming Hugo would let you do that…never tried stomping on the taxonomy URL namespace). It would require some external scripting or something to generate fake pages somehow. :man_shrugging:

If you’re hosting your site with Netlify or have control of the web server, you can use a custom 404 template that shows an empty list depending upon the request URL. But the server will likely still return a 404 status code (if that matters).

1 Like

From this I am assuming that you are managing these links and constructing them yourself. What you could do, if you don’t want a 404 is to check via GetPage first, something like:

{{ with site.GetPage "categories/foo" }}
  link to categories/foo
{{ else }}
  link to categories list or placeholder page or not link at all
{{ end }}

Doc: Taxonomy Templates | Hugo

1 Like

That seems right, but I would at least try these three options:

  1. create a “fake” page that is not built using build parameters in the frontmatter, see:

    Build Options | Hugo

    I am not sure if setting this all to private and no-build will lead to the tag disappearing.

  2. treat the “tags” directory as a section and create a tags/tagname/ for all tags that you want to list, then filter “pages by section = tags”

    I am not sure if Hugo will let you do that or just return nil because the ‘section’ is not a real section in sense of Hugo content.

  3. have a list of predefined tags in a data template, then every time you list all tags merge it with the existing tags and filter out doubles.

1 Like

Thanks a lot! Yes I have a full grip on the links.

I imagine your suggestion as follows: given a /categories/nonexisting path, the server would have to check if the first node is categories and then test if the second node is defined in categories and act accordingly. Is that correct?

This sounds cleanest, but since the page is static I have trouble imagining the implementation (and probably this would require a modification of the built-in taxonomy system?) Do you know where would this logic go exactly? You can assume a completely standard template

Following this thread (thanks guys!):

As a quickfix I like the idea of providing an informative 404. Something like: "If you were looking for a specific category, it may have been renamed or empty: Click [here] to see all currently existing tags". This is least-effort for me and easy to understand (although we have that 404 status which may be a bit pesky).


  1. This is also very low effort, but may confuse potential future maintainers/users that don’t bother with the comments, docs or any slides that I may prepare. I see this as the less brittle variant of providing them with default content. In all cases worth considering.

  2. I went a little along these lines and it seemed to me that I ended up being redundant (and worse) to Hugo’s built-in functionality. Yes, you fix this issue but create potentially many others. I wouldn’t go this way at my level of knowledge/understanding.

  3. Let me reinterpret your suggestion (and merge it with @pointyfar’s one): In the .toml config file, I can add a list of default tags that must always be rendered, even if empty. Then, somewhere, I tell Hugo to list them under a particular taxonomy class.

Currently I went for the informative 404, but I would love to have something along the lines of 3 working. That would be low-maintenance, robust, easy to understand and completely flexible (custom taxonomies etc).

Documentation. Documentation. Documentation. :smiley:
Even if that future maintainer is YOU. Speaking out of experience here. I am heavily documenting everything. ({{- /* note */ -}} helps)

This [my suggestion] all happens Hugo-side, before it hits your server. No modifications are needed to how the taxonomy works.

If categories/foo does not exist,

  • no page will be created at
  • {{ site.GetPage "categories/foo" }} will be nil (or something similar)
  • the else block runs
  • If users manually visit url they will get a 404 (because point 1)

Of course you could expand this to also check if categories exists at all first.

You can create a page manually for that: Taxonomy Templates | Hugo