Hugo: Leaf and Branch Bundles

Hello all,

I have been noticing on-going confusion about bundles, and vs, and Halp! I upgraded, and none of my content pages show up! :smile:

I had tried to explain this concept in a draft post earlier, but now here it is, in complete detail (with a flow chart too), an understanding of this Page Bundles feature as I see it:

@bep @regis, all: I’d welcome comments/corrections in that post.


Nice! Your post will help a lot of people.

Two things:

  • I feel the post did not make it obvious enough that md files inside a leaf bundle will not be considered pages while md files inside a branch bundle will. This maybe worth repeating a few times.
  • You should mention that the homepage (/ can be a branch bundle itself. This is something I did not know.

Your notice about file type, makes me think I can use json to create content files (pages). If so, do you just enter the content in a “content” key? That deserves a post in itself :slight_smile:

Thanks for sharing!

Thank you! Your feedback is the kind I was exactly looking for, thanks!

I did mention that, but now I have made it more prominent; added that to the comparison table too.

I had mentioned this, but rephrased it to include homepage term.

Honestly, I picked that up from existing documentation, but I removed the json reference because it didn’t feel right… as I haven’t tried it personally…

The post is now updated with your suggested clarifications.


Wait, is “branch bundles” even a thing? Aren’t these just sections or subsections?

To me @bep’s notion of bundle is like a tar-ball of resources that appear as a single page, with being the main resouce, and the rest being auxiliary resources that are private to the bundle (not accessible by other pages).

By that defition, sections are not bundles and referring to them as such is just going to sow confusion.

See also: Branch Bundles and Leaf Bundles


They are not just sections… they are sections + the power of Resources.

Branch bundles do “tar-ball” in all the resources, except page resources… so you can use image processing, etc. with branch bundles too.

By calling the directories with as branch bundles, it helps clarify that these are not the default sections… they are sections with Resources.

I didn’t follow… I already know about that thread because the OP in that thread is referring to my earlier draft of this blog post, and I am also replying in that thread.

I forgot to mention, that I appreciate this dialogue; it will help clarify this concept for me and many others.

In reply to that question, I have updated the Branch box in the flow chart (Maybe Ctrl+F5 to get the new image).

Guess what… :smile:

Maybe we should pin your post in the forum.

It’s been 2 months since Hugo 0.32 and some people still haven’t found out that is reserved for Resources… :sleeping:

Or send a PR to the Hugo Docs. But on second thought I think that @bep prefers to keep the documentation spartan and to the point.

Anyway good article @kaushalmodi hopefully it will help spread the word.

1 Like

There’s a draft entry for the docs on page bundles. Might be worth noting (or maybe not), that I’m using leaf bundles solely for the headless feature (a regular section in every way, but utilizing headless). That was a feature request of mine and this is a wee bit of a hack, but it appears to work).

And thanks for writing that post!

1 Like

Correct! I had authored that draft, and it was just sitting there, and then I came up with an idea to create a flowchart… This blog is a blend of that draft + flow chart + links to examples and undrafted official documentation.

Why do it think it’s a hack… it definitely works and as designed.

Yeah, I guess you’re right. I just think of the feature aimed at using images.

Talking about headless bundles, I just updated the post and added an example of headless bundle usage too.

1 Like

FYI, instead of this:

$reusablePages := $headless.Resources.Match "*"

I did

$reusablePages := $headless.Resources

Not sure if there’s a material difference between the two, but the Match "*" felt like it might be resource intensive.


Slightly, but mostly your version looks better.

Also see

I spent more time than I care to admit to fix a site that I inherited. The interesting part is that depending on the fixes to the bundle, some other part of the site would fail to build correctly. One thing that would help tremendously is not only to log errors or warnings with debug messages but if the debug log is enabled, log why a page is not rendered, rather than silently not doing anything.


That documentation was in draft state for over a month… and I had pestered you a few times to undraft it. Looks like you were just waiting for me to convert that draft to my personal blog post to finally undraft it …

To better address that question, I have now added a new sub-section to my post:

I’m still not getting the raison d’être of bundles.

Is it this and only this? Why not simply have resource lookup and manipulation method(s) that can work for any resources anywhere in the content tree? Why all this cognitive and code complexity? By complexity I mean look at all the if…else if…else… logic implicit in understanding all the rules (pretend you’r a newb and read your page or the official docs

I appreciate it too. I’m a believer in power through simplicity and coherency, and am trying to influence Hugo in that direction. I believe much of the confusion in Issues and forum posts reflects unnecessary complexity.

btw, @kaushalmodi, image your site appears to have been taken over by aliens.

Hmm? Just checked that the site is still up… didn’t get that reference :slight_smile:

That statement you quoted me on was specific to branch bundles.

I don’t know the Go implementation details, so cannot comment on that. But the leaf vs branch concept seems straightforward to me.

That section is “old”… .Page.BundleType got added in Hugo 0.40. But in general, you need to understand any new concept to use it correctly.