Single-page template lookup order doesn't behave as documented

[geealbers]

When a page has both a type and a layout, according to this example in the documentation, Hugo will look for various templates in your project that explicitly match your layout name, say layout: grid, but will eventually fallback to the other defaults, all the way down to /themes/<THEME>/layouts/_default/single.html. However, the more generic fallbacks aren't actually built into the system, and if Hugo does not find a template with the explicit layout name, the page fails to build completely.

Here's a sample warning you get with --verbose that (I assume) shows all the places Hugo tried to look for a template for rendering the given page with layout: grid:

WARN 2017/08/16 16:58:52 [en] Unable to locate layout for "page": [post/grid.html.html post/grid.html _default/grid.html.html _default/grid.html theme/post/grid.html.html theme/post/grid.html theme/_default/grid.html.html theme/_default/grid.html]

The inner workings of Hugo and Go are a bit beyond my skills, but the issue seems to arise in the fact that Hugo assigns any page without an explicit layout to be equivalent to layout: single. So then, the template lookup order is either going to include the custom layout value, or the single default layout value, but can never include both custom and single. I believe the relevant code starts in hugo/output/layout.go lines 270–72, and then proceeds from there:

if layout == "" {
  layout = "single"
}

I discovered the issue when trying to use the layout parameter to simply add classes to an existing page layout. (So, I didn't have or need a template file, just an {{ if eq .Params.layout "grid" }} call in the default page template.) This of course can be accomplished any number of other ways, but regardless, it seems like the underlying inconsistency should be addressed either by editing the documentation to match the current behavior, or by changing the Hugo layout code to match the documentation. Depending on the maintainers'/community's desired outcome.

Happy to help with the documentation part, but if the the Go is to be rewritten instead, afraid I'll need to leave that to someone else.

[bep]

@geealbers thanks for this detailed report. Yes, I see what you mean and how this can be surprising. I rewrote the whole template lookup logic earlier this year to make it easier to test and extend, but I'm pretty sure that I followed the old logic.

That assumption would make the documentation wrong, but looking at it now I think the current behaviour is surprising and should be changed -- and changing it should not break (too much).

@rdwatters I assume you wrote the doc part on this... thoughts?

[rdwatters]

Thanks @geealbers for pointing this out. So it seems like there are maybe two ideas being discussed here:

1. Correcting current docs.
2. Enhancements to current lookup order.

1

If this is a matter of just correcting the docs, I'll open up a separate issue in hugoDocs. I think the small gotcha is worth calling out; i.e., if you declare a layout and Hugo doesn't find the declared layout, it will not fall back to, in this case, _default/single.html. Just a matter of creating a note admonition at the bottom of the referenced example, as well as removing #'s 3,4,5,8,9,& 10 from the list in the docs.

2

Using the same example, I think what you're talking about would be documented as follows, @geealbers? I'm only mentioning this for my own clarification and since @bep marked this as an enhancement:

1. /layouts/review/reviewarticle.html
2. /layouts/posts/reviewarticle.html
3. /layouts/review/single.html
4. /layouts/posts/single.html
5. /layouts/_default/reviewarticle.html
6. /layouts/_default/single.html
7. /themes/<THEME>/layouts/review/reviewarticle.html
8. /themes/<THEME>/layouts/posts/reviewarticle.html
9. /themes/<THEME>/layouts/review/single.html
10. /themes/<THEME>/layouts/posts/single.html
11. /themes/<THEME>/layouts/_default/reviewarticle.html
12. /themes/<THEME>/layouts/_default/single.html

Seems this would be a better separation of concerns for content files that that only declare a layout but allow Hugo to assume thetype or for content files that only want to add type for content files that deviate from other files in a section.

That said, with output formats, bundles, etc, my assumption is that this is a pretty big ask, @bep? Thanks!

[geealbers]

Thanks to you both. I think if it's not too much trouble to change the behavior and allow Hugo to always fallback to a single.html template, that's ideal from a user perspective. And in that case, yes @rdwatters, your second (2) approach to the docs list looks good to me, though perhaps no. 5 in the list would move up to the third position and no. 11 would move to the ninth position? So, in effect, Hugo looks everywhere for the layout-specific template reviewarticle.html first, and then if it doesn't find it, it goes back to those same locations to look for then simple.html template instead.

1. /layouts/review/reviewarticle.html
2. /layouts/posts/reviewarticle.html
3. /layouts/_default/reviewarticle.html
4. /layouts/review/single.html
5. /layouts/posts/single.html
6. /layouts/_default/single.html
7. /themes/<THEME>/layouts/review/reviewarticle.html
8. /themes/<THEME>/layouts/posts/reviewarticle.html
9. /themes/<THEME>/layouts/_default/reviewarticle.html
10. /themes/<THEME>/layouts/review/single.html
11. /themes/<THEME>/layouts/posts/single.html
12. /themes/<THEME>/layouts/_default/single.html

[Jonarod]

I was about to open issue for exactly this same problem... Check my post on the forum if new ideas are welcome as well, but generally speaking _default should just act as default... :)

[jmooring]

The template lookup order documentation is generated from code; it correctly describes the behavior. I suspect a number of related things have changed since this issue was created 6 years ago.