.Kind (page): .Type (hugodocs) / .Layout ()
Bundle: n/a (regular page)
[ categories | projects | tags | search ]
Hugo Sandbox

This is an unofficial Hugo sandbox site to try to replicate possible bugs in hugo.

It is updated automatically after each commit to the hugo-sandbox repo. It was last updated on Jan 20, 2022 13:08 UTC.


This page was created/modified in commit 8144987 "Add toc to page bundle doc" on 2018-02-02.
Markdown source of this page

Page Bundles

categories: content management bundle


Description/Summary

Content organization using Page Bundles

Content

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
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 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.
</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:

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:

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.


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


This site is generated using the ox-hugo package for Emacs/Org-mode + hugo-bare-min-theme + Hugo 0.92.0 (commit b3549403) .

[Back to Hugo Sandbox home]