I have been noticing on-going confusion about bundles, and index.md vs _index.md, and Halp! I upgraded, and none of my content pages show up!
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.
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 (/_index.md) 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
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 index.md 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.
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 _index.md 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.
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).
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.
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 …
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 Hugo: Leaf and Branch Bundles ❚ A Scripter's Notes or the official docs Page bundles | Hugo).
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.