Page Bundles
categories: content management bundle
Description/Summary
Content organization using Page BundlesContent
Table of Contents
Page Bundles are a way to organize the content files. It’s 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
Leaf Bundle | Branch Bundle | |
---|---|---|
Usage | Collection of content and attachments for single pages | Collection of content and attachments for section 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 |
Allowed Nested Resources | Page and non-page (like images, pdf, etc.) type | Only non-page (like images, pdf, etc.) type |
Leaf Bundles
A Leaf Bundle is a directory at any hierarchy within the content/
directory, that contains at least an index.md
file.
</div>
<div class="admonition-content">
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 MIME type recognized by
Hugo (json
files will, as one example, work fine). If you want to
get exotic, you can define your own media type.
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 theindex.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
.
</div>
<div class="admonition-content">
The hierarchy depth at which a leaf bundle is created does not matter, as long as it is not inside another leaf bundle.
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 inpublic/
. - 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
</div>
<div class="admonition-content">
Only leaf bundles can be made headless.
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.
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.
</div>
<div class="admonition-content">
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 MIME type recognized by
Hugo (json
files will, as one example, work fine). If you want to
get exotic, you can define your own media type.
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.
</div>
<div class="admonition-content">
The hierarchy depth at which a branch bundle is created does not matter.
-
The
.md
extension is just an example. The extension can be.html
,.json
or any of any valid MIME type. ↩︎