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.