Hugo: Rename taxonomy kinds

[bep]

This have been discussed before and I thought it wasn't important enough to warrant a potential breaking change.

After the Page.GetTerms discussion we had I have looked at the taxonomy documentation, and it's murky and hard to understand, and I think this is a little bit because we don't have the terms in precise order.

I have looked at this more closely, and I think we can do this without too much noise. The .Page.Kind is mostly an internal "thing", but leaks out into the template/config in some places -- but not so much for the taxonomies as, say, section and regular pages. The most important part is the template selection, and there we should be safe.

So, I suggest we fix this before it's too late.

Currently we have taxonomyTerm (where I guess it was meant that it's a _list of terms_) and then each term is a taxonomy.

I suggest we introduce a new term and use the terms used for this in the documentation:

If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at /content/\

So:

• taxonomyTerm => taxonomy (holds a list of terms)
• taxonomy => term

I will try to make this as backwards compatible as possible (ref. disableKinds etc.), and that is a little easier when we're not just swapping them (and I kind of like the shorter term).

For the template logic I see no problems.

case "taxonomy":
        if d.Section != "" {
            b.addLayoutVariations(d.Section)
        }
        b.addKind()
        b.addSectionType()

    case "taxonomyTerm":
        if d.Section != "" {
            b.addLayoutVariations(d.Section + ".terms")
        }
        b.addTypeVariations("taxonomy")
        b.addSectionType()
        b.addLayoutVariations("terms")

What do you say @regisphilibert @onedrawingperday @digitalcraftsman @kaushalmodi and gang? Go for it?

[onedrawingperday]

Looks good. It will simplify things.

However I think that this change could be a breaking one.

It would be best if we tested it with Hugo DEV before it made it into a release.

[bep]

@onedrawingperday you're right. I'll try to do it early in the next iteration.

[regisphilibert]

Yes I'm glad we'll try and sort this out before 1.0.

The proposed naming might still break change and make noise though. Especially if people are using term as a content type. But the porposal has the very strong appeal of being fully consistent with the current naming of other Kinds

• homepage: the landing page for the homepage
• page: the landing page for a given page
• section: the landing page of a given section

Proposal follows same rule:

• taxonomy: the landing page for a taxonomy (and potentially its list of terms, but could be anything user chooses)
• term: the landing page for one taxonomy's term

Avoiding breaking changes

We could come up with some ugly new Kind names to remove all aforementioned potential issues.

• taxonomyTerm => taxo
• taxonomy => taxoTerm

Alignment with template names

I think we should make sure this change will not be a detriment to the intuitivity of the current template naming. So I'll just draft a table with the new Kind naming so we can:

1. Confirm I'm right, cuz I very well might be missing something
2. Confirm it retains its intuitivity.

Other people can add some more examples.

template name | old kind | new kind | landing page of... | url
-- | -- | -- | -- | -- |
tags/list.html | taxonomyTerm | taxonomy | the tags taxonomy | /tag
tags/terms.html | taxonomy | term | a term of the tags taxonomy | /tag/art

---

Note: I was not able to create a dedicated template for the landing page of the art tag using the documented tags/art.terms.htmlor tags/art.terms.html.html

[kaushalmodi]

To avoid breakage, may be:

• taxonomyTerm => termList
• taxonomy => term

I think above would be quite self explanatory and also will not break anything.

---

If not above, the proposed breaking change is better than what we have now :D

[regisphilibert]

taxonomyTerm => termList

The fact that the page display a list of terms is up to the coder. What is factual is that it will be the landing page for a given taxonomy. So I don't think termList is more appropriate than taxonomy or taxo.

[bep]

@kaushalmodi my thoughts on this. The potential breakage is:

• People using Kind in where or if clauses
• People using Kind in CSS classes

And maybe some variations of the above.

I have not seen any of the above in the wild, but I'm sure it is out there ... But not much, and we're doing this to fix a pedagogic/documentation issue for all the rest of us, it's for the greater good etc...

So, we're going with taxonomy and term.

[kaushalmodi]

@bep Then I did not understand the extend of this renaming.. a lot of themes would have _default/taxonomy.html and _default/terms.html. Those would be unaffected?

There are also the taxonomy and taxonomyTerm in the [outputs] in config.toml.

About:

People using Kind in where or if clauses

I think many themes would be using that. Just from looking at first few pages of this Github search (their search is horrible, but I don't know how else to search for stuff like this): https://github.com/search?l=HTML&q=%22.Kind%22+taxonomy&type=Code, many people are matching .Kind with "taxonomy" and "taxonomyTerm".

---

As for me, I am always fine with doing the right thing, even it if means I need to refactor stuff. I am just making a note that this would be a pretty big breaking change.

[kaushalmodi]

@regisphilibert

The fact that the page display a list of terms is up to the coder.

Makes sense.. may be just taxo? I don't know.. I was just throwing out ideas so that the switch can happen without breaking anything.. and Hugo can introduce warnings when people use the then old "taxonomy" or "taxonomyTerm" kinds... and finally remove the refs to those old kinds completely in 1.0 release.

[regisphilibert]

I am just making a note that this would be a pretty big breaking change.

FWIW I agree with @kaushalmodi, even if it's less graceful that the original proposal, we should use two new keys and not reuse any of the current ones.

[kaushalmodi]

given that taxo and terms are related, what you proposed earlier makes sense (to have that "taxo" part in both Kind strings):

• taxonomyTerm => taxo
• taxonomy => taxoTerm

[bep]

@kaushalmodi template selection will be unaffected. You will get one more _default/term.html etc. that will possibly improve the situation, but there will be no breakage here.

For the others we will make it as backwards compatible as possible (most people who disables taxonomy also disables taxonomyTerm, so that will work).

As I'm the one doing the coding here, I will say this: For the amount of work involved, creating 2 new values that does not map directly to the terms used in the documentation, is not worth the amount of work required.

[regisphilibert]

creating 2 new values that does not map directly to the terms used in the documentation

I'm not sure to follow, two new keys will be added, and documented. Two old keys will, while still being effective, not be documented anymore and eventually retired.

That being said, we of course realize anything not as straight forward as the original proposal is going to generate more work on your hands and we don't want that. But we should expect some breaking changes most of them from themes, and those can be noisy as users have to wait for themes to be updated.

Maybe we should just give an early warning to theme authors beforehand, so they can get ready for the change.

Maybe we can prepare a quick snippet for them.

```
{{ $taxonomyKind := "taxonomy" }}
{{ $termKind := "term" }}
{{ if lt hugo.Version "0.66.0" }}
{{ $taxonomyKind = "taxonomyTerm" }}
{{ $termKind = "taxonomy" }}
{{ end }}

{{ if eq .Kind $taxonomyKind }}
[...]
{{ end }}

{{ range where .Pages ".Kind" $termKind }}
[...]
{{ end }}
``` 

[kaushalmodi]

creating 2 new values that does not map directly to the terms used in the documentation

I don't follow that either. Anyways "taxonomyTerm" and "taxonomy" will be replaced with new keys, say, A and B. I would have imagined that doing search/replace (as only initial part of the entire refactoring), it would be much simpler if the new keys don't match with either of the old keys. But of course you are the best judge there.

And the docs will anyways need to update to use the new keys. So that effort stays the same.

[bep]

I don't follow that either. Anyways "taxonomyTerm" and "taxonomy" will be replaced with new keys, say, A and B. I would have imagined that doing search/replace

• Search and replace
• Then add some legacy support in outputs and disableKinds (and possibly some other places) + add tests for that legacy support. This is to reduce the last part.
• Update documentation
• Handle complaints about breakage here and on the forum

So, even if we replace both terms with something completely different, we have to do all 4 above. Maybe we get a little less of the last one.

The reason I'm rooting for taxonomy/term is to get both 1. easy to understand and 2. consistency when talking about these in the documentation.

To add content to a Page of kind term, add a content file to /content/<TAXONOMY>/<TERM>/_index.md and add your metadata in its front matter. To add content to a Page of kind taxonomy, add ...

Compare that to:

To add content to a Page of k ind taxoTerm, add a content file to /content/<TAXONOMY>/<TERM>/_index.md and add your metadata in its front matter. To add content to a Page of kind taxo, add ...