Hugo: docs: Improve docs for `_index.md` etc.

[didenko]

From what I understood in the new documentation and the discussion forum Hugo 0.18 supports rendering of _index.md files in sections, while index.md should not work. However, I am seeing varying behaviours, including the opposite one. An example is provided via the attached hugo018index.zip file.

Here is what is in the example:

hugo018index $ find . -type file
./bare/config.toml
./bare/content/_index.md
./bare/content/test/index.md
./bare/layouts/_default/single.html
./bare/layouts/index.html
./under/config.toml
./under/content/_index.md
./under/content/test/_index.md
./under/layouts/_default/single.html
./under/layouts/index.html

hugo018index $ diff -r bare under
Only in under/content/test: _index.md
Only in bare/content/test: index.md

hugo018index $ diff bare/content/test/index.md under/content/test/_index.md; echo $?
0

hugo018index $ 

In other words, the example has two directories with identical data, except in the bare directory the test section has index.md, while in the under directory the test section has identical _index.md.

Opposite my expectation things do work when running hugo server in the bare directory, and do not work when running hugo server in the under directory.

Are my expectations wrong, or there is a Hugo issue?

[bep]

Are my expectations wrong, or there is a Hugo issue?

You should then start by defining your expectations. I have read your issue twice, and I don't understand it.

However, I am seeing varying behaviours, including the opposite one.

Yes, that is true. The order of page generation is undefined -- so sometimes you get lucky, i.e. the single page gets rendered before the section list. Hugo renders in parallel, which is one of the reasons it is so fast.

[didenko]

Hey, do not mean to steal your Xmas, this can wait :) Seriously, though my expectation is in the first sentence, that "Hugo 0.18 supports rendering of _index.md files in sections". In attached code _index.md in the test section fails to render - either in the homepage list or as a single page at http://localhost:1313/test/.

[bep]

You may get a hint if you run it with hugo -v

WARN: 2016/12/23 21:19:56 site.go:1804: Unable to locate layout for page : [section/test.html _default/section.html _default/list.html indexes/test.html _default/indexes.html]

I'll keep this issue open so someone can have it as a tracking issue to improve the documentation in this area.

[didenko]

OK, I see it as well.

I will go with with _default/section.html in this case, seems to work. Will look closer into how to put that content also into the homepage.

Thank you!

[bep]

Also see https://discuss.gohugo.io/t/is-this-doc-still-valid-content-list-template/4919

[McPringle]

The compatibility information for updates from Hugo 0.17 to 0.18 about _default/section.html should be added to the documentation and the release notes! That solved my problem, too. But I had no warning about the missing template file. I render the sites always with -v for verbose output. I know a few more (at least six) public Hugo themes which are broken with Hugo 0.18 because they miss this template file. I'll go and create issues or PRs there.

Thank you very much @didenko for creating this issue/discussion.

[bep]

I know a few more (at least six) public Hugo themes which are broken with Hugo 0.18 because they miss this template file.

If you know about at least six themes that do not provide a _default/list.html template or similar, you should report that on the themes' issue trackers. I just did a search in all the themes at https://github.com/spf13/hugoThemes and found only one theme with a potential problem in this area.

As to documentation updates: Someone have to write it, and contributions are welcome.

[podiki]

The issue may not be as easy to spot in other pages, like the about page for the cactus theme. There is a _default/list.html but not a section/about.html. With Hugo 0.18 the about page no longer renders. In this case copying layouts/about/single.html to layouts/section/about.html solves the issue for me. Then the about page will be content/about/_index.md. See the issue I added for that theme. So the problem can be quite confusing in different themes, hopefully this information helps sort it out going forward.