Trying to understand spurious(?) "home page is blank" warnings

support
1

When creating a public/index.html from content/index.md, I noticed that Hugo emits a “home page is blank” warning. I reported this on the issue tracker (spf/hugo#3002), but since @bep closed the issue and told me to discuss this here, I would appreciate any help in understanding this behaviour.

Steps to reproduce

hugo new site hugo-temp
cd hugo-temp
mkdir layouts/_default
echo '{{ .Content }}' > layouts/_default/single.html
echo Hello world > content/index.md
hugo
cat public/index.html

Expected behaviour

  • Hugo should create a new public/index.html file containing “<p>Hello world</p>”.
  • Hugo should not emit any warnings.

Actual behaviour

  • Hugo creates the file public/index.html as expected.
  • Hugo emits the following warning:
=============================================================
Your rendered home page is blank: /index.html is zero-length
 * Did you specify a theme on the command-line or in your
   "config.toml" file?  (Current theme: "blank")
 * For more debugging information, run "hugo -v"
=============================================================
2

You have created a single page with the same URL as the home page (/index.html).

The only way this works is that you also did not provide a template for the home page or the other list pages (try creating _default/list.html).

If you had provided that template, you would see a random behaviour – sometimes you would get one or the other page.

We could make this more intelligently and not create a warning in this case (we will not), but that would make it more complex than needed and would throw out all the parallelism that makes Hugo so blistering fast.

3

I see, thanks. I seem to have missed this comment in the docs:

The home page template is a special kind of List template.

Is there a non-hacky way to make Hugo render content from a markdown file in the content directory to public/index.html using the “single” layout without copying layouts/_default/single.html to another location?

(The typical use case for this would be a site which only consists of simple “single” pages.)

4

No, but if what you want is a 1 page site then

  • layouts/index.html
  • content/_index.md

Would be appropriate.

5

Sure, but what about a simple site that consists of “index”, “about”, “contact”, … (which should all be rendered using the same template)? That’s one of the cases where the new “_index.md” feature comes in really handy.

I just helped two friends of mine to convert sites to Hugo and both could have gotten away just with the “single” layout.

Some thoughts regarding possible workarounds:

  • Manually setting layout = "single" in _index.md does not work because _index.md is always rendered using the list template.
  • Abusing the “list” layout by setting layout = "list"in all markdown files and creating layouts/_default/list.html works in some cases but seems rather cumbersome.
  • Symlinking layouts/index.html to layouts/_default/single.html does not work either (“Symbolic links for directories not supported”).
6

This has been discussed before. Use the search.

7

I have used the search and the upshot seems to be “This is currently not possible without using duplicate layout files” (somewhat mitigated by using a dummy partial or similar workarounds).

I am simply trying to a) confirm this b) understand why homepages (_index.md) are always considered a subtype of list.

Since my original question has been answered and I understand the warnings now, I will simply open a new thread for this question.