# Default theme layout doesn't seem to be recognized

**URL:** <https://discourse.gohugo.io/t/default-theme-layout-doesnt-seem-to-be-recognized/17599>\
**Category:** support\
**Created:** [March 16, 2019, 1:44am UTC](https://discourse.gohugo.io/t/default-theme-layout-doesnt-seem-to-be-recognized/17599 "2019-03-16T01:44:07Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![clozach](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/clozach/32/8035_2.png) [@clozach](https://discourse.gohugo.io/u/clozach)\
**Post date:** [March 16, 2019, 1:44am UTC](https://discourse.gohugo.io/t/default-theme-layout-doesnt-seem-to-be-recognized/17599/1 "2019-03-16T01:44:07Z")

</div>

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

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

```

```bash
~/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

```

```auto
~/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:

```auto
~/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`…

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

[About](/about)

```

…and this in the `about` index:

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

# About Me

```

## Problem

The home page renders just fine:

 ![27](https://canada1.discourse-cdn.com/flex036/uploads/gohugo/original/2X/d/d14b8c43b19fdc19dc6f73fc80254a1044b2e8de.jpeg)  
☝`http://localhost:1313/`

But the `about` index is blank:

 ![29](https://canada1.discourse-cdn.com/flex036/uploads/gohugo/original/2X/5/55e79c09355f096392294f9d53352eb44ee791d0.jpeg)  
☝`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?

---

<div class="post-metadata">

**Author:** ![pointyfar](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/pointyfar/32/5797_2.png) [@pointyfar](https://discourse.gohugo.io/u/pointyfar)\
**Post date:** [March 16, 2019, 1:53am UTC](https://discourse.gohugo.io/t/default-theme-layout-doesnt-seem-to-be-recognized/17599/2 "2019-03-16T01:53:55Z")

</div>

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](https://gohugo.io/content-management/page-bundles/)
- Layout lookup order [here](https://gohugo.io/templates/lookup-order/#hugo-layouts-lookup-rules)

---

<div class="post-metadata">

**Author:** ![clozach](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/clozach/32/8035_2.png) [@clozach](https://discourse.gohugo.io/u/clozach)\
**Post date:** [March 16, 2019, 5:18am UTC](https://discourse.gohugo.io/t/default-theme-layout-doesnt-seem-to-be-recognized/17599/3 "2019-03-16T05:18:31Z")

</div>

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** 🤦‍♂️  
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”. 😉

**Misunderstanding** 🤔:  
During my search for answers, I came across the [Page Kinds documentation](https://gohugo.io/templates/section-templates/#page-kinds), which says this:

 ![page-kinds-excerpt](https://canada1.discourse-cdn.com/flex036/uploads/gohugo/original/2X/0/0ad1ec50898215b46f7f6be3c47972d30df3c7b7.png)

The implication seemed to be a [section](https://gohugo.io/content-management/sections/) (i.e., `/foo/_index.md`) should map to an `index.html` template.

This seems to be in direct conflict with the first [Lookup Rule](https://gohugo.io/templates/lookup-order/#hugo-layouts-lookup-rules), 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`?

---

<div class="post-metadata">

**Author:** ![Jura](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jura/32/13581_2.png) [@Jura](https://discourse.gohugo.io/u/Jura)\
**Post date:** [March 16, 2019, 5:32am UTC](https://discourse.gohugo.io/t/default-theme-layout-doesnt-seem-to-be-recognized/17599/4 "2019-03-16T05:32:06Z")

</div>

> [@clozach](#):
>
> The implication seemed to be a [section](https://gohugo.io/content-management/sections/) (i.e., `/foo/_index.md` ) should map to an `index.html` template.
> 
> This seems to be in direct conflict with the first [Lookup Rule](https://gohugo.io/templates/lookup-order/#hugo-layouts-lookup-rules), which reads:

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. 🙂

---

<div class="post-metadata">

**Author:** ![maiki](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/maiki/32/16384_2.png) [@maiki](https://discourse.gohugo.io/u/maiki)\
**Post date:** [March 16, 2019, 5:37am UTC](https://discourse.gohugo.io/t/default-theme-layout-doesnt-seem-to-be-recognized/17599/5 "2019-03-16T05:37:35Z")

</div>

> [@clozach](#):
>
> 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` ?

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_](https://gohugo.io/content-management/sections/) | `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! 🙂

---

<div class="post-metadata">

**Author:** ![pointyfar](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/pointyfar/32/5797_2.png) [@pointyfar](https://discourse.gohugo.io/u/pointyfar)\
**Post date:** [March 16, 2019, 9:04am UTC](https://discourse.gohugo.io/t/default-theme-layout-doesnt-seem-to-be-recognized/17599/6 "2019-03-16T09:04:44Z")

</div>

I _think_ I understand your confusion. To add to @maiki above, by default, Hugo renders your content with [pretty URLs](https://gohugo.io/content-management/urls/#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 😅

---

<div class="post-metadata">

**Author:** ![clozach](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/clozach/32/8035_2.png) [@clozach](https://discourse.gohugo.io/u/clozach)\
**Post date:** [March 16, 2019, 7:31pm UTC](https://discourse.gohugo.io/t/default-theme-layout-doesnt-seem-to-be-recognized/17599/7 "2019-03-16T19:31:49Z")

</div>

Aha… 💡!

@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` |
> | … | | |

# &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ⬇

> | 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.