Why do child _index.md files override parents?

I’ve made a couple of sites with Hugo now and consider myself pretty proficient, but I’ve got a content organization issue which is flummoxing me to no end. Here’s the deal:

Let’s imagine that I have a site which sells gift bags. Every gift bag contains a list of items. Here’s what my content looks like. You can see that I’ve got two bags: chocolates, and flowers.

├── addons
│   ├── _index.md
│   ├── candles.md
│   └── soap.md
└── bags
    ├── _index.md
    ├── chocolates
    │   ├── _index.md
    │   ├── dark.md
    │   └── milk.md
    └── flowers
        ├── _index.md
        ├── dahlia.md
        └── tulips.md

The _index.md file in /bags/ contains metadata about the bags section.

---
title: Our Amazing Bags
---

Each bag’s _index.md contains information about the bag itself, e.g.:

---
title: Bag O' Chocolate
price: $15
---

and the rest of the files contain information about the items in the bag. e.g.:

---
title: Milk Chocolate
type: item
---

Now, here’s what I don’t understand: when I navigate here:

https://localhost:1313/bags/

I see the title not from bags/_index.md – but from bags/flowers/_index.md!

What’s more, I would expect .Data.Pages in the /bags/ section to contain the bags. It doesn’t. It only contains the items. Here’s the layouts/_default/section.html file from my template:

<h1>Section: {{ .Title }}</h1>

{{ range .Data.Pages }}
  {{ .Render "single" }}
{{ end }}

I think I’m missing something fundamental about the new “everything’s a page” model in Hugo. What is it, and how would you organize this content?

I thought the same thing, but I think the answer (or the solution, because I don’t have an explanation) is that the index file in the sub-topics should not have the beginning underscore. So,

--chocolates
    |-- index.md

rather than

--chocolates
    |-- _index.md

That’s what worked for me.

I got the idea of using _index.md from here (bottom of page):

I was hoping to use the directory structure to imply the content structure, but it looks like .Data.Pages doesn’t return anything on those index.md files. I’ll look into setting up a taxonomy to take this over the line. Very much appreciate the help!

When I looked at your scenario, I was thinking taxonomies might be the way to go. Yeah, not sure about the underscore, but removing it helped me.

I’ve been fooling around with doing this your way (I have a situation similar to yours, @jmcphers) and am confused too. If I use {{ printf "%#v" . }} on the template I see the _index data there but I’m having a hard time outputting the content I’d like.

Note that Hugo currently only supports 1 level of sections, so there is only bags, and – while this could probably have been handled better – there is only room for 1 _index.md file per section, and I’m guessing now it is kinda random.

This will improve in the future, though.

1 Like

@bep, the documentation page I linked in my earlier comment clearly shows more than one _index.md file per section. Should that be updated?

We have an open issue about improving the docs in this area, but the docs are correct: What you see is not sections, but taxonomies (which have 2 levels).