hugo/docs/content/content-management/page-bundles.md

title	description	date	lastmod	linktitle	keywords	categories	toc	menu
Page Bundles	Content organization using Page Bundles	2018-01-24T13:09:00-05:00	2018-01-28T22:26:40-05:00	Page Bundles	page bundle leaf branch	content management	true	docs identifier parent weight page-bundles content-management 11

Page Bundles are a way to group Page Resources.

A Page Bundle can be one of:

• Leaf Bundle (leaf means it has no children)
• Branch Bundle (home page, section, taxonomy terms, taxonomy list)

	Leaf Bundle	Branch Bundle
Usage	Collection of resources (pages, images etc.) for single pages	Collection of non-page resources (images etc.)for list pages
Index file name	index.md 1	_index.md 1
Layout type	single	list
Nesting	Doesn't allow nesting of more bundles under it	Allows nesting of leaf/branch bundles under it
Example	content/posts/my-post/index.md	content/posts/_index.md

Leaf Bundles

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.

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.

{{% note %}} The hierarchy depth at which a leaf bundle is created does not matter, as long as it is not inside another leaf bundle. {{% /note %}}

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 }}

In this example, we are assuming the some-headless-bundle to be a headless bundle containing one or more page resources whose .Name matches "author*".

Explanation of the above example:

1. Get the some-headless-bundle Page "object".
2. Collect a slice of resources in this Page Bundle that matches "author*" using .Resources.Match.
3. Loop through that slice of nested pages, and output their .Title and .Content.

---

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

headless = true

{{% note %}} Only leaf bundles can be made headless. {{% /note %}}

There are many use cases of such headless page bundles:

• Shared media galleries
• Reusable page content "snippets"

Branch Bundles

A Branch Bundle is any directory at any hierarchy within the content/ directory, that contains at least an _index.md file.

This _index.md can also be directly under the content/ directory.

{{% note %}} Here md (markdown) is used just as an example. You can use any file type as a content resource as long as it is a content type recognized by Hugo. {{% /note %}}

Examples of Branch Bundle organization

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

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

branch-bundle-1

This branch bundle has the _index.md, two other content Markdown files and two image files.

branch-bundle-2

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

{{% note %}} The hierarchy depth at which a branch bundle is created does not matter. {{% /note %}}

---

1. The .md extension is just an example. The extension can be .html, .json or any of any valid MIME type. ↩︎