Improve warning for missing layout

[ghost]

When missing layouts, Hugo presents this output:

WARN 2019/12/18 19:42:47 found no layout file for "HTML" for "home": You should
create a template file which matches Hugo Layouts Lookup Rules for this
combination.

WARN 2019/12/18 19:42:47 found no layout file for "HTML" for "page": You should
create a template file which matches Hugo Layouts Lookup Rules for this
combination.

WARN 2019/12/18 19:42:47 found no layout file for "HTML" for "section": You
should create a template file which matches Hugo Layouts Lookup Rules for this
combination.

WARN 2019/12/18 19:42:47 found no layout file for "HTML" for "taxonomyTerm": You
should create a template file which matches Hugo Layouts Lookup Rules for this
combination.

However, this output is not quite helpful. A skilled user might find this page:

https://gohugo.io/templates/lookup-order

but a novice user might not, in which case they will have no idea how to fix the
problem. Further, even if they find the page, its not clear still how to resolve
the issue. For example if you search taxonomyTerm, it doesnt take you to a
section that lists proper paths. Youd have to know to navigate to this section:

https://gohugo.io/templates/lookup-order#examples-layout-lookup-for-taxonomy-terms-pages

I think it would be more helpful for Hugo to emit these anchored links. That way
upon error a person can navigate directly to the section of the help page to
solve the problem.

Another option would be for Hugo to simply emit what its searching for,
something like:

WARN 2019/12/18 19:42:47 found no layout file for "HTML" for "taxonomyTerm" in
these paths: [layouts/categories/category.terms.html.html
layouts/categories/terms.html.html layouts/categories/list.html.html
layouts/categories/category.terms.html layouts/categories/terms.html
layouts/categories/list.html layouts/taxonomy/category.terms.html.html
layouts/taxonomy/terms.html.html layouts/taxonomy/list.html.html
layouts/taxonomy/category.terms.html layouts/taxonomy/terms.html
layouts/taxonomy/list.html layouts/category/category.terms.html.html
layouts/category/terms.html.html layouts/category/list.html.html
layouts/category/category.terms.html layouts/category/terms.html
layouts/category/list.html layouts/_default/category.terms.html.html
layouts/_default/terms.html.html layouts/_default/list.html.html
layouts/_default/category.terms.html layouts/_default/terms.html
layouts/_default/list.html]

I get that this is verbose, so it could be hidden behind --verbose or
--debug. Currently neither flag exposes this output.

[ghost]

Here is a cheat sheet:

found no layout file for "HTML" for "home": layouts/_default/index.html

https://gohugo.io/templates/lookup-order#examples-layout-lookup-for-home-page

---

found no layout file for "HTML" for "page": layouts/_default/single.html

https://gohugo.io/templates/lookup-order#examples-layout-lookup-for-regular-pages

---

found no layout file for "HTML" for "section": layouts/_default/section.html

https://gohugo.io/templates/lookup-order#examples-layout-lookup-for-section-pages

---

found no layout file for "HTML" for "taxonomy": layouts/_default/taxonomy.html

https://gohugo.io/templates/lookup-order#examples-layout-lookup-for-taxonomy-list-pages

---

found no layout file for "HTML" for "taxonomyTerm": layouts/_default/terms.html

https://gohugo.io/templates/lookup-order#examples-layout-lookup-for-taxonomy-terms-pages

[frerich]

I like this idea - I think it's perfectly fine to be verbose when it comes to warnings or errors:

1. You typically won't (or rather: should not) have too many of them, so the verbosity wouldn't add up
2. You should look into resolving the issues one way or another: more verbose output would accelerate getting a resolution.

[bep]

The idea is good, but I think the right thing is to just suggest the first path we look for each.

[ghost]

@bep I would consider the files I listed in the "cheat sheet" to be the canonical paths. Its going to differ depending on language and taxonomy settings, but I think its a good starting point.

Also I think they are better than using list.html, as I have found that to be ambiguous. It seems list.html can be used in different contexts. This can be useful for reducing code duplication, but I found its worth the duplicated code for clarity.

[bep]

@cup I suggest that we use your "cheat sheet", but with a couple of mods:

• found no layout file for "HTML" for "section": layouts/_default/list.html or layouts/_default/section.html
• found no layout file for "HTML" for "home": layouts/index.html

It is very common to have the home page template on the top level.

[ghost]

@bep I dont like the list.html for "section" as it can be used in other
contexts. For example it can be used for Home as layouts/list.html or
layouts/_default/list.html. Buts thats my preference so its not a big deal
either way.

And I like layouts/_default/index.html for Home as it allows you to have
everything in the same folder, _default, but again thats a person preference.

Your suggestion wouldnt be my ideal, but its definitely an improvement from the
current warnings. Thanks

[zaitseff]

I too found the current output of the warnings at times frustrating: Hugo knows exactly what it is looking for, why make me guess what it wants? I would prefer the suggestion by @cup to list the complete list of paths, at least as part of "--verbose". If I have time in the next few days, I'll look into producing a pull request for this very thing, although I'm currently a Go beginner!

[bep]

@cup keeping everything in _default makes sense, but I still think listing list.html and section.html as the two common section options makes sense. We have recently cleaned up the page tree API to make it symmetrical from top to bottom, so even if I think most people will have a dedicated home page template, having all other list pages share one list.html seems like a common enough pattern that we should tell people about it.

@zaitseff listing every options makes it too noisy, considering languages, output formats and legacy lookup variants.

[zaitseff]

Alternatively, I suggest modifying the renderForLayouts and/or findFirstTemplate functions in hugolib/site.go to print a DEBUG statement on every template lookup (successful or otherwise), with a warning when one is not found:

DEBUG 2019/12/23 09:18:00 looking for layout file for "HTML" for "taxonomyTerm" in [layouts/categories/category.terms.html.html layouts/categories/terms.html.html layouts/categories/list.html.html layouts/categories/category.terms.html layouts/categories/terms.html layouts/categories/list.html layouts/taxonomy/category.terms.html.html layouts/taxonomy/terms.html.html layouts/taxonomy/list.html.html layouts/taxonomy/category.terms.html layouts/taxonomy/terms.html layouts/taxonomy/list.html layouts/category/category.terms.html.html
layouts/category/terms.html.html layouts/category/list.html.html layouts/category/category.terms.html layouts/category/terms.html layouts/category/list.html layouts/_default/category.terms.html.html layouts/_default/terms.html.html layouts/_default/list.html.html
layouts/_default/category.terms.html layouts/_default/terms.html layouts/_default/list.html]
WARN 2019/12/23 09:18:01 found no layout file for "HTML" for "taxonomyTerm": you should create a template file which matches the Hugo Layout Lookup Rules for this combination; pass "--debug" to hugo for a list of paths being searched.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.