I get the same result on Ubuntu 24.04.3 LTS with:
And the same result on Windows:
Forget about partials for a minute, and consider this:
content/
└── p1.md
layouts/
├── foo.bar.html
├── foo.html
└── page.html
content/p1.md
---
title: p1
layout: foo.bar
---
Q: Which template will it use?
A: layouts/page.html
Q: Why doesn’t it use layouts/foo.bar.html?
A: Because the bar segment of the foo.bar.html file name is an invalid identifier; it is not a valid page kind, language, output format, etc. With an invalid identifier in the file name, this template is excluded from the list of possible matches.
Q: If bar is an invalid identifier, why doesn’t it just use layouts/foo.html?
A: Because you told it to use foo.bar.
Q: Why does it use page.html?
A: Because it’s a valid fallback.
If you wanted a custom template that you could call with the words foo and bar in the file name, use something other than a dot to separate them (e.g., foo-bar). The dot indicates separation of identifiers (page kind, language, output format, etc.) used in template lookups.
For this whole post of yours, I get that now. Hugo assigns special meanings when you use a period. I was thinking of it like, if I renamed an image from myimage.jpg to my.image.jpg, the image still works perfectly fine. Hugo doesn’t like that though when it comes to partials. I saw the GH issue you opened up. That’s fair.
For your example in your repo, if I use the latest commit (8001061348ee82689b38a5cdba0f77fab0bf12a4), it doesn’t work. I get the same partial used for all 3 examples. This is the commit where you commented out the output type stuff in the config.
If I use the second to latest commit (85ba29b97d402363218301d07ba774e929c3217d), where the output type is defined in the config, it does actually work.
The problem is, I’m not defining my partials by output type. I was trying to do it by section. Some sections, if a partial is there, I wanted to use a more specific header. For example, in the docs section, a header that changes the title and uses a custom logo. My website happens to have an output type but that’s just a coincidence.
For example, I made a new branch, partials-issue, on my site repo. I made some changes. I removed every single reference of JSON Feed. The partial, the directory in content, the outputtype in the config, everything. This way we don’t get bogged down in output types. In _partials I have:
header.html
header.blog.html
header.docs.html
When I visit /docs on the site, which is in the docs section, I expect headers.docs.html to be used. It is not. The same issue when I visit /blog.
For those who might be following along and don’t want to run my site/click links, the following 3 screenshots are from the displayed header when running the site. The homepage is correct, the two section pages are not.
The baseof.html file that rendered these, has this relevant section:
{{ $headerTpl := "header" }}
{{ with .Section }}{{ $headerTpl = printf "%s.%s.html" $headerTpl . }}{{ end }}
<p>DEBUG: Partial should be: _partials/{{ $headerTpl }}</p>
{{ partial $headerTpl . -}}
Not just partials… any template type.
And at this point I don’t understand if you still have a problem or not given my explanation of identifiers in the file name… green, blue, etc. are not valid identifiers.
I do. I laid it out in my most recent post.
Neither “blog” nor “docs” are valid identifiers.
So then we does Hugo docs mention “section” as part of the lookup for the partials? Those are section names.
The word “section” refers to the “section” page kind. Valid page kinds are home, page, section, taxonomy, and term.
Okay…
So look at this new commit: Use kind names instead · linodians/www.linodians.com@35d4fdf · GitHub
I made _partials/header.section.html file. In baseof.html, I tell it to use the partial name header.section.html. Every page uses the new section even though the homepage is of kind “home” and the contact page is of kind “page”. If in baseof.html I tell it to use header.html, then all pages simply use that. There isn’t any fallback by kind.
Partial calls are not context-aware. I think we’ve already discussed this:
Unlike other template types, Hugo does not consider the current page kind, content type, logical path, language, or output format when searching for a matching partial template.
So back to my question, what is the point of it? Why does the docs mention the word “section” there when it doesn’t fall back by section, or if you want to consider it a kind, it doesn’t fall back to kinds. The example doesn’t make sense.
All I’ve seen today is that it does fall back by language, which the docs mention, and apparently by output type, which the docs does not mention. By section or kind, it does not, which the docs leads you to believe.
I’m obviously unable to explain this to your satisfaction. Perhaps someone else can do a better job. Feel free to add suggestions to the issue I created in the docs repo.
I’ll wait a bit before I try to ping anyone. I already DM’d you but thank you for your time. I really appreciate it.
Just some thoughts - maybe they light up, may be they send us deeper in the mist.
maybe some of these are valuable for the docs, maybe all is nonsense
TL;TR;
I must admit when following your dialog, each time i though I got it, i failed - I think the most confusing thing is my feeling that it’s unclear where
Which for me the choice which template is taken is not affcted by any of these “senses” meen but only depends on the name of the file.
but then
Seems also terms between dots may not be any string. but why all these identifiers kind, section, … are ignored…?NO
it does not matter if I use section or page as second term it just matches the one in the partial call but it has to be a valid one - it’s unclear why we have to use page/section if there’s no meaning behind.
I can call “header.section.oops.html” which will use this template if it’s there mmh, third one is language?
{{ partial "header.page.oops.html" . }}
header.page.oops.html if it’s there
header.page.bla.html → sound like it’s ment for splitting up blocks/baseof by kind.
→ there’s a somehow “unnecessary” binding to the kind, maybe language.
… I guess not many use that “most specific” rules and I guess many get hit when trying to…
a.b and having a.c calling a.b.cwill match supposedly a.b (untested)and yes @jmooring I much appreciate the time and patience you spent on this issue.
If a feature is too difficult to understand or explain, we should get rid of it.
Let’s just remove the partial lookup example from the docs, and say that partial templates should be named a.b, where a cannot contain a dot, and b must be a valid media type suffix. And reiterate the fact that they are not context-aware.
I’m obviously tired of this thread.
yes, there’s a basic thing that works as you said .. and this would be a good approach for the docs.
If that’s a feature we want to keep, the advanced usage could be added with the new structure.
but also then it has some confusing glitches which need some explanation.
If that’s a feature we want to drop, keep in mind that working stuff will be used… documented or not - especially if it has been there before.
currently I have a closer look in “whats” happening
I’ll add my findings to the GitHub issue if you don’t mind.
Regarding to this thread - for me it can be archived, but that’s a question to the OP @FelicianoTech
We’re not going to do that. The existing lookup example is technically correct with valid use cases:
https://github.com/gohugoio/hugo/pull/13614#issuecomment-2805977008
If you find a bug with the lookup order, that’s a software issue, not a documentation issue.
With respect to partial calls not being aware of the the current context, I’m not sure how to make this any clearer:
Unlike other template types, Hugo does not consider the current page kind, content type, logical path, language, or output format when searching for a matching partial template.
Maybe putting the partials first and the list of the other templates last? And/or establishing what Hugo considers first before mentioning what it does not consider? Negations are always harder to grasp.
The current version may well be correct, but it places a considerable covering burden on the reader, especially if English is not their native language.
but it consider all partials as non matching if the page kind is illegal which is … very hard to understand if it’s “not considered”