HUGO

:slug in the context of taxonomies

According to the documentation, the value for :slug, if not explicitly overridden, is determined by the name of the content file. However, after doing some experimentation and looking at the files generated in the public folder, that doesn’t seem to be strictly the case. This is what I put in my config.toml file:

[taxonomies]
year = "year"

[permalinks]
year = "/post/:slug/" 

And in my front matter:

year: 2021

When I look at the public folder, this is what I see:

post
-2021
–index.html
–index.xml

So to me it looks as if, in the case of a slug for a taxonomy, :slug by default refers to the term of the taxonomy, and not to the name of the markdown file. I’d just like to know whether I’m misunderstanding how this works. Thanks.

https://gohugo.io/content-management/urls/#permalink-configuration-values

:slug
the content’s slug (or title if no slug is provided in the front matter)

I do not understand what you’re trying to do here.

So, if, for example, I create a permalink like this:

[permalinks]
post = "textfiles/:slug"

This means, as I understand it, :slug is being replaced with firstpost or secondpost, or whatever the names of the markdown files are in the section post. So when I generate the public folder I get paths like:

textfiles/firstpost
textfiles/secondpost

Indeed, if I do that I get a hierarchy like this in my public folder:

textfiles
-firstpost
–index
-secondpost
–index

This is what I would expect, based on that quote from the documentation.

However, if, instead of a section, I am binding(?) a permalink to a taxonomy, I get the result I showed in my original post, which is not in accord with that quote from the documentation. It looks like the paths being generated from

year = "post/:slug/"

are like this:

post/2020
post/2021

not like this:

post/firstpost
post/secondpost

Am I missing something, or does the documentation need to be updated?

No.

:slug is replaced with slug from the post’s front matter, and if that is not specified it falls back to the title specified in the post’s front matter.

With a taxonony or term page, the title defaults to the name of the taxonomy or term unless you have created _index.md pages for those items (e.g., content/tags/_index.md, content/tags/foo/_index.md).

Finally, your permalink configuration is setting the permalink of taxonomy pages, not content pages.

What are you trying to accomplish?

1 Like

Thanks for the correction with regard to the :slug being replaced by the title. That makes sense. And what you say here:

With a taxonony or term page, the title defaults to the name of the taxonomy or term unless you have created _index.md pages for those items

basically clears up my confusion, but then you say that my permalink configuration is setting the permalink of taxonomy pages, not content pages. I didn’t think that it was setting the permalink of content pages, but it looks to me that I am setting the permalink of term pages, not taxonomy pages. I still have a taxonomy page under the URL site.com/year/ (Correct me if I’m wrong).

To further clarify, the contents of the public folder looks like this (the term page, from the permalink configuration):

Is this correct?

You are correct. I meant term pages. In my defense, the internal vocabulary changed a few months ago. Term pages used be called taxonomy pages, and taxonomy pages used to be called taxonomy term pages. This was cleaned up in v0.73. There may be still be some places in the documentation that do not reflect the revised terminology.

This configuration:

[permalinks]
year = "post/:slug/"

[taxonomies]
year = "year"

with this content:

content
├── post
│   ├── post-1.md   (front matter: year = ["2021"])
│   ├── post-2.md   (front matter: year = ["2021"])
│   └── post-3.md   (front matter: year = ["2021"])
└── _index.md

Generates this HTML:

public/
├── post
│   ├── 2021
│   │   ├── index.html
│   │   └── index.xml
│   ├── post-1
│   │   └── index.html
│   ├── post-2
│   │   └── index.html
│   ├── post-3
│   │   └── index.html
│   ├── index.html
│   └── index.xml
├── year
│   ├── index.html
│   └── index.xml
├── index.html
├── index.xml
└── sitemap.xml

So I think you’re good.

1 Like

Thank you!

Keep in mind, if you were to create this content:

hugo new post/2021.md

it would be overwritten when you build the site.

Running hugo --path-warnings will tell you something’s wrong:

WARN 2021/03/19 17:44:21 Duplicate target paths: ....
1 Like

Thanks, I’m making a note of it.