Default theme layout doesn't seem to be recognized

support
1

Despite quite a lot of time perusing the docs, as well as various googling, I seem to be misunderstanding something fundamental about the way _index.md's get rendered.

In order to try to understand Hugo better, I’ve started a site from scratch with a super minimal (read “not bothering with HTML just yet”) layout.

Setup

~/testsite/content $ tree
.
├── _index.md
└── about
    └── _index.md

~/testsite/themes/gohugo-theme-clatch $ tree
.
├── LICENSE
├── archetypes
│   └── default.md
├── layouts
│   ├── 404.html
│   ├── _default
│   │   ├── baseof.html
│   │   ├── list.html
│   │   └── single.html
│   ├── index.html
│   └── partials
│       ├── footer.html
│       ├── head.html
│       └── header.html
├── static
└── theme.toml

~/testsite $ cat config.toml 
baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Zugo Site"
theme = "gohugo-theme-clatch"

As I said, the layout’s super basic for now:

~/testsite/themes/gohugo-theme-clatch $ cat index.html 
{{ define "main" }}
{{ .Page.Title }}
{{ .Content }}
{{ end }}

Content-wise, I’ve got this in the root _index.md…

~/testsite/content $ cat _index.md 
---
title: Zome page test
date: 2019-03-01
---
# First content

[About](/about)

…and this in the about index:

~/testsite/content $ cat about/_index.md 
---
title: "About Index"
date: 2019-03-03
---

# About Me

Problem

The home page renders just fine:

27
271024×768 79.9 KB

:point_up:http://localhost:1313/

But the about index is blank:

29
291024×768 66.8 KB

:point_up:http://localhost:1313/about/

Question

What am I doing wrong?

In my tests, I can get the about page to render if I duplicate the root index.html and rename it to: themes/gohugo-theme-clatch/layouts/about/list.html. So, more specifically:

How do I create a default layout for index.html pages?

2

Hi,

So the short answer is that _index.md needs a list.html layout, while an index.md needs a single.html layout.

Long answers are:

  • Page bundles (index.md vs _index.md) here
  • Layout lookup order here
3

Thanks for the rapid reply, @pointyfar!

This solves the specific problem, but I still have some confusion….

Fwiw, I had read both of the docs you shared, but got turned around by the combination of a “silly” mistake and a misunderstanding.

Mistake :man_facepalming:
I didn’t realize that layouts/_default/list.html was empty. On the one hand, I’d run into this problem with layouts/index.html in the first place, which is why it’s a silly mistake. On the other hand, I suspect I’m not the only Hugo novice to ever feel confused by the emptiness of the scaffold files, hence the quotes around “silly”. :wink:

Misunderstanding :thinking::
During my search for answers, I came across the Page Kinds documentation, which says this:

page-kinds-excerpt
page-kinds-excerpt1088×185 19 KB

The implication seemed to be a section (i.e., /foo/_index.md) should map to an index.html template.

This seems to be in direct conflict with the first Lookup Rule, which reads:

The page Kind (the home page is one). See the example tables below per kind. This also determines if it is a single page (i.e. a regular content page. We then look for a template in _default/single.html for HTML) or a list page (section listings, home page, taxonomy lists, taxonomy terms. We then look for a template in _default/list.html for HTML).

Follow-up Question

Is the Page Kinds documentation incorrect, or am I missing some sublety about the usage of index.html when it’s in a layout subdirectory, like /about/index.html or /posts/index.html?

4

There’s no contradiction since these are two different things.

(1) The /foo/_index.md page is turned by Hugo into the /foo/index.html page, as the outcome of how Hugo renders the static website. This does not affect the layout of that page, but simply the HTML output.

In the same way, my /posts/first-blog-post.md is turned by Hugo into the /posts/first-blog-post/index.html file. If you run the hugo command you’ll see that Hugo renders an index.html file by default for each content file it renders into static HTML.

(2) The lookup order is which theme template Hugo uses to render the page. These can be single.html, list.html, index.html and so on depending on the kind of content. But these can also be sitemap.xml or custom-output.txt depending on how Hugo should turn our content files into static output.

Informally, Hugo uses this process for that:

  • Hugo takes the content file (say /posts/_index.md).
  • It then looks which template file applies to that content file (say /_default/list.html).
  • It then uses that template file to make the output file. In that case the data from my _index.md file (like its title and actual content) is combined with the template file (list.html) to render the output: the /posts/index.html file.

That file is then ready to be served by our web server. :slight_smile:

5

The table in question is copied:

Every Page in Hugo has a .Kind attribute.

Kind Description Example
home The home page /index.html
page A page showing a regular page my-post page ( /posts/my-post/index.html )
section A page listing regular pages from a given section posts section ( /posts/index.html )
taxonomy A page listing regular pages from a given taxonomy term page for the term awesome from tags taxonomy ( /tags/awesome/index.html )
taxonomyTerm A page listing terms from a given taxonomy page for the tags taxonomy ( /tags/index.html )

Hmmm, I think the answer to your question is: the example in that chart is talking about the output in the public directory when a site is built, whereas in most contexts in the docs we talk about files ending with .html as templates (files that live in themes or layouts).

Honestly, I’m not sure what information the examples column provides. And when I think about it we probably should make a single document explaining page kinds, since it is explained in pieces across the docs. Someone make a todo! :slight_smile:

6

I think I understand your confusion. To add to @maiki above, by default, Hugo renders your content with pretty URLs. This means that everything is rendered (as in in your public folder) as an */index.html, ie:

content/hello.md => /hello/ which really means /hello/index.html.

This index.html is not the same index.html that you put in the layouts. If you set uglyURLs = true in your config you should see that.

Edit: Basically repeating what @Jura has already explained nicely above :sweat_smile:

7

Aha… :bulb:!

@maiki I like your idea to improve the docs. I wonder if this one-word addition wouldn’t suffice as a short-term improvement:

Kind Description Example
home The home page /index.html
…

                       :arrow_down:

Kind Description Example Output
home The home page /index.html
…

?

Seems almost too trivial for a pull request, but I’d be happy to do it anyway if any of you think it’s appropriate.

@pointyfar, @maiki, and @Jura, you all rock! Thank you so much for the help.

1 Like