I have some posts with permalink: /example/ in the frontmatter. I was confused they were causing an error until I read this and had to bulk change from permalink to slug both in the front matter and the config file. What is the logic behind not supporting "/:permalink/"?
A permalink is a full identifier. The slug is just the last part. You could regulate your content by putting stuff into arbitrary folders and build your resulting URLs via:
url: /the/full/url/to/this/post.html
or
slug: post.html
In the latter case the containing folder might have an _index.md with a slug of the-page. The full URL would be /the-page/post.html.
This gives you more power over the resulting URL structure of your website.
For instance useful for putting different sections into the same URL-section, but using different layout files.
But I am referring to frontmatter specifically, not necessarily the folder structure.
me too. frontmatter configures your content.
OOh. I get your point. So you mean slug bypasses the directory structure?
yes, frontmatter parameters url and slug both bypass the directory structure.
I’m not sure if I understood correctly but in any case …
The slug setting is only for the last part of a permalink structure.
- A permalink is:
https://domain.tld/some/path/post_name/ - The slug in the permalink is:
post_name
Also, the slug frontmatter is optional. In the absence of it, Hugo will use the title frontmatter as the slug. (Also, if I remember correctly, the default is if title is also not present, it will use the filename of the filename.md file next, to form the slug.)
This is good because you can structure your permalinks independent of your folder structure.
For example, in my [permalinks] section in config.toml I have:
blog = "/:slug-:year:yearday/"
c = "/:sections[1:]/:slug-:year:yearday/"
The blog and c above are actual folders, as shown below, is my folder structure:
/content/eng-ph/blog/posts/2021/some-post-file.md
/content/c/poems/2020/some-post-file.md
When Hugo generates the site, the permalinks are:
https://domain.tld/post_name-365/
https://domain.tld/poems/post_name-123/
In both examples, the folder 2021 and 2020 are not in the resulting permalink. You will also notice in the second example, the poems folder remains intact but not the c folder.
My case was why Hugo sends a 404 error if I have permalink: /abc-def/ in the posts frontmatter, but doesn’t if I use slug: or url: and I am still confused about this.
You cannot set permalink in front matter.
Use url instead.
Why not? Any reason in the docs?
https://gohugo.io/content-management/urls/
permalinks is for site configuration.
url is for front matter.
Sorry, I don’t know how to make this any clearer.
The decisions regarding url management (globally and per content file) were made by Hugo’s original creator and other contributors a very long time ago.
We cannot provide you with the reasons why these features were designed in a specific way -as we are not the ones who created the software-.
Also the documentation site is not meant to provide the reasons behind the software’s architecture.
This is an important question since I was moving my second site from Jekyll to Hugo and it has permalinks defined in front matter using permalink: /example/. So, brushing this away does not answer my question in the first place! Anyways, it is not a big deal, but I wasted time figuring out I needed to use slug or URL instead.
I think I will stick with this explanation. Having hundreds of posts with permalink: /example/ in the front matter throw an error does make me apprehensive of why this is the case, since other I could not find any explanation online.
I do not think that I brushed anything away. Rather I gave you an informed reply.
The doc is crystal clear.
You really have to read the documentation there is no way around it.
Also before opening further topics please do read the:
These forum guidelines were put in place years ago to save time.
Both your time -as you found out the hard way- but also our time.
4 Likes
This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.