Hugo: Leaf and Branch Bundles

Hugo v0.32 introduced a new feature called Page Bundles (1, 2), as a way to organize the content files. It is useful for cases where a page or section’s content needs to be split into multiple content pages for convenience, or has associated attachments like documents or images.

A Page Bundle can be one of two types:

• Leaf 🍃 Bundle
• Branch 🌿 Bundle

Quick Summary #

Here’s a quick summary of the differences between these bundle types — Details follow in the sections after.

Leaf Bundle #

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

Examples of Leaf Bundle organization #

content/
├── about
│   └── index.md
├── posts
│   ├── my-post
│   │   ├── content1.md
│   │   ├── content2.md
│   │   ├── image1.jpg
│   │   ├── image2.png
│   │   └── index.md
│   └── my-another-post
│       └── index.md
└── another-section
    ├── ..
    └── not-a-leaf-bundle
        ├── ..
        └── another-leaf-bundle
            └── index.md

In the above example content/ directory, there are four leaf bundles:

about

This leaf bundle is at the root level (directly under content directory) and has only the index.md.

my-post

This leaf bundle has the index.md, two other content Markdown files and two image files. The content from the two non-index .md files can be accessed only as page resources, not as regular files i.e. those non-index .md files will not have their own permalinks or HTML files in public/.

my-another-post

This leaf bundle has only the index.md.

another-leaf-bundle

This leaf bundle is nested under couple of directories. This bundle also has only the index.md.

Headless Bundle #

A headless bundle is a bundle that is configured to not get published anywhere:

• It will have no Permalink and no rendered HTML in public/.
• It will not be part of site.RegularPages, etc.

But you can get it by site.GetPage. Here is an example:

{{ $headless := site.GetPage "page" "some-headless-bundle" }}
{{ $reusablePages := $headless.Resources.Match "author*" }}
<h2>Authors</h2>
{{ range $reusablePages }}
    <h3>{{ .Title }}</h3>
    {{ .Content }}
{{ end }}

A leaf bundle can be made headless by adding below in the Front Matter (in the index.md):

headless = true

Example uses of headless page bundles:

• Shared media galleries
• Reusable page content “snippets”

Branch Bundle #

A Branch Bundle is a directory at any hierarchy within the content/ directory, that contains an _index.md file. This _index.md can also be directly under the content/ directory, to set the Home page content and/or front-matter variables.

By default, Hugo considers the first directory level under content/ as a section. But a branch bundle can be used to create a section at any hierarchy.

Examples of Branch Bundle organization #

content/
├── _index.md
├── branch-bundle-2
│   ├── branch-content1.md
│   ├── branch-content2.md
│   ├── image1.jpg
│   ├── image2.png
│   └── _index.md
└── branch-bundle-3
    ├── _index.md
    └── a-leaf-bundle
        └── index.md

In the above example content/ directory, there are three branch bundles (and a leaf bundle):

Home page as branch bundle

The home page content is organized as a branch bundle, using _index.md directly in the content/ directory. It consists of two other branch bundles.

branch-bundle-2

This branch bundle has the _index.md, two other content Markdown files and two image files. The content from the two non-index .md files can be accessed only as regular pages, not as page resources. Branch bundles cannot have page resources, so any non-index Hugo recognized content file in a branch bundle can be accessed like any regular page (just like in any section.. as.. a branch bundle is a section too).

branch-bundle-3

This branch bundle has the _index.md and a nested leaf bundle.

Branch Bundle vs Regular Sections #

Branch Bundle section

Any directory in content/ that contains the _index.md file.

Regular Section

Any first-level directory in content/, and also home page and taxonomy list page .. that is not already a Branch Bundle.

Here’s an example snippet that can be used in a list template to distinguish between the two:

{{ if (eq .Kind "section") }}                          <!-- Section -->
    {{ if (eq .File.Path "") }} <!-- Regular section -->
        <h1>Posts in ‘{{ .Dir | default .Section }}’</h1>
    {{ else }}                  <!-- Branch bundle section -->
        <h1>{{ .Title }}</h1>
        <h2>Posts in ‘{{ .Dir | default .Section }}’</h2>
    {{ end }}
{{ end }}

So, which bundle should I use? #

In summary:

• If it’s a regular page or a single page where you write your content yourself, create a leaf bundle.

  Page Bundles of page Kind are always leaf bundles.. and vice versa.

• Otherwise, if it’s a list page which Hugo generates for you, create a branch bundle. Such pages typically are a list of regular pages or even other list pages. Pages of home, section, taxonomy and term Kind are always branch bundles.

Upgrading to Hugo v0.32? #

All of this boils down to these few caution points if you are upgrading Hugo from a pre-0.32 version to 0.32 or a newer version:

• If a directory foo has an index.md (leaf bundle), that file will be the content file for that foo Regular Page.
• If a directory foo has an _index.md (branch bundle), that file will be the content file for that foo Section Page, and all other² .md files in the same or deeper hierarchy levels under foo/ will become Regular Pages under that foo section.

Examples #

Of course, a post like this is not complete without examples, so here they are:

Further Reading #

I suggest reading the below pages in the Hugo documentation, as they complement the Page Bundles concept:

• Content Organization
• Page Resources
• Image Processing