What am I doing wrong? Lookup order issue, with complete example

I’ve read the documentation, I’ve searched the topics, but it’s still not clear why is the lookup order is wrong.

Here’s this example: https://github.com/dotleon/leafbundlelayoutissue

According to the documentation, this is the lookup order for the “/leafbundle/” in the example:

Single page in “posts” section

This means that “/content/leafbundle/index.md” should render from “/layouts/leafbundle/single.html”. But it renders from “/_default/single.html” instead.

For whatever reason, this works right with a branch bundle, see /branchbundle/ in the example.

I feel like the documentation is in the wrong here, as /_default/ gets priority over /leafbundle/, but only if I use “index.md” (leaf bundle) instead of “_index.md” (branch bundle).

This got closed as an issue, so I suppose it’s my understanding of the lookup order that is wrong, but I couldn’t figure this out the whole day.

Could somebody explain why /leafbundle/ is not working in my example as one would expext?

Others please correct me if I’m wrong, but this is what I think is happening.

So this file:


Is equivalent (layout-wise) to this file:


In both cases, the layouts/_default/single.html template will be used.

Now, if you delete that content file, then create:


You will get the result you’re expecting, aka the layouts/leafbundle/single.html template will be used.

This is because content/leafbundle/some-post.md is actually a leaf bundle, whereas your previous content file is not. Hope this helps.



Hope this helps

It doesn’t really help, as you create an _index.md too, which is a branch bundle. Branch bundle templating lookup works as expected, as documented.

Leaf bundles don’t.

This is because content/leafbundle/some-post.md is actually a leaf bundle, whereas your previous content file is not. Hope this helps.

From the documentation:

Leaf Bundle
Usage: Collection of content and attachments for single pages
Index file name: index.md


A Leaf Bundle is a directory at any hierarchy within the content/ directory, that contains an index.md file.

I’m still not convinced. This still very much sounds like a bug. Either in the documentation, or the way it actually works.

I can see the potential confusion.

cc @kaushalmodi as he will likely have a better explanation.

1 Like

No, think of /content/leafbundle/index.md as /content/leafbundle.md but as a Leaf Bundle. /content/leafbundle/index.md is not technically inside a “leafbundle” section.

/layouts/leafbundle/single.html applies to pages in leafbundle “section”.

1 Like

If you look at this table:

Look at the row with “layout” in it. There is no “layout in folder lookup” in any of those variations.

1 Like

Single page in “posts” section with layout set

  • layouts/posts/demolayout.html.html
  • layouts/posts/single.html.html
  • layouts/posts/demolayout.html
  • layouts/posts/single.html

/content/leafbundle/index.md is not technically inside a “leafbundle” section.

This is the part I couldn’t comprehend up until this point. I think I understand now.

I really appreciate all of your input, things can get a little confusing until you have a solid grasp of what’s what.

I’ve managed to get over this issue by putting the demolayout.html into the _default folder, but it really bugged me that I didn’t understand why it’s not working, but now I do.

I’ve always hated web programming, but with hugo I’m actually enjoying it.

Thank you for helping!

PS: awesome community


That said, you may want to look into setting Type in front matter (aka posts in the example).

1 Like

In addition you might want to look at this great explanation from @regis:


I found exactly the same issue. Thanks @dotleon and everyone for working through this!

My scenario was essentially trying to create a new layout by converting content/post-xyz.md to content/post-xyz/index.md, which lead me to think that we can just use layouts/post-xyz/single.md because this documentation page about Page Bundles shows that a leaf bundle is just a page of type single.

So long story short - the simple option is just to use:

  1. an explicit front matter entry layout = post-xyz in index.md above
  2. add layouts/_default/post-xyz.html
1 Like