Confused about taxonomy pages

1

I’m getting a bit confused when reading the documentation about taxonomy pages.

I currently have 2 taxonomies:

[taxonomies]
  category = "categories"
  theme = "themes"

Other content types are associated with a taxonomy by doing:

categories: ["foo"]
themes: ["bar"]

I’m also adding metadata to taxonomy pages, so my site structure will look like:

/content
  - themes
    - bar.md
    - tea.md
  - categories
    - foo.md
    - coffee.md

When I generate my site, i’m getting the following structure:

/categories
  - index.html -> layouts/categories/list.html
  - foo
     - page
        - 1 -> layouts/categories/list.html
          - index.html
     - index.html -> layouts/categories/list.html
  - coffee
     - index.html -> layouts/categories/single.html
/themes
  - index.html -> layouts/themes/list.html
  - bar
     - page
        - 1 -> layouts/themes/list.html
          - index.html
     - index.html -> layouts/themes/list.html
  - tea
     - index.html -> layouts/themes/single.html

A few questions regarding this:

  1. Why is themes/index.html using the same template as themes/bar/index.html? The first one would be a list of all theme taxonomies, while the second one is an individual taxonomy with its content. How can I make these use different templates
  2. Why is themes/coffee/index.html is using single.html? They both represent the same thing, except that coffee doesn’t have any content associated to it.
2

A few things are going wrong in your example.

Have a read on:

That will clarify everything. You basically need the correct layout template pages, separately for the taxonomyTerm (categories, themes) and taxonomy (coffee, bar) pages. I use terms.html for taxonomyTerm pages, and reuse the default list.html for taxonomy.

Because you put foo.md pages in the content directory! Hugo has no way of knowing if you meant those to be regular content, or pages specific to your taxonomies. So it always assumes the former. Move those files to a structure like content/themes/bar/_index.md. See Page bundles | Hugo.

And lastly, I was experimenting with these very recently. You can find my detailed post with examples here. The example post links in there further link to the source Markdown files on the respective pages. The theme I use is also linked in the footer of those example pages if you want to peek at the terms.html and list.html layout files.

3

Thanks for the information, understood about the layout lookups.

If I understand it correctly:

/layouts
  - themes
     - list.html -> Taxonomy list page for themes
     - theme.html -> Single taxonomy page

This setup seems to work.

This is slightly confusing, why would it treat themes/bar differently from themes/tea? They both are taxonomy terms, but yet themes/tea is treated as a different type. How can I make it behave like a taxonomy term?

One I associate another post with tea, it’s treated the same as themes/bar. It seems that if no post are associated with a taxonomy term, it’s treated as a single page.

4

Hmm, probably… But if you do it the expected way, by using _index.md, there will be no ambiguity.

5

Is using _index.md the supported way? Because now I’m more confused. I might be missing something completely obvious here.

/content
  - themes
    - foo.md -> uses layouts/themes/list.html
    - bar
      - _index.md -> uses layouts/_defaults/list.html
    - aa.md -> no posts associated uses layouts/_defaults/single.html
6

Yes, _index.md is the supported way for specifying content and front matter for non-regular pages* or "list"pages like sections, taxonomies, etc. The directories with _index.md (note the underscore) are called branch bundles.

For regular page foo, you can specify its content as foo.md or foo/index.md (note the lack* of underscore).

Don’t mix regular pages with taxonomy pages in your content/themes.

If you consistently use _index.md for all taxonomy and taxonomyTerm pages, you’ll see consistency in the results too. From your last example, you are not doing that!

7

I’d suggest this example of mine (not sure if you followed through to the examples link in my last to last post…):

8

Yes, because I wanted to prove my point that something isn’t working very logically.

If I don’t use _index.md, the template would be layouts/themes/list, if I use _index.md, the template would be layouts/_defaults/list

And using foo/_index.md doesn’t seem very logical, that would imply there could be more pages under foo. While it’s just a simple taxonomy term, thus only having one page.

9

But you are right that using themes/foo/_index.md makes all terms behave the same. I found out that the correct template would be layouts/taxonomy/theme.html.

It still seems a bit odd to do foo/_index.md instead of just foo.md