Page bundles

Introduction

A page bundle is a directory that encapsulates both content and associated resources.

By way of example, this site has an “about” page and a “privacy” page:

content/
├── about/
│   ├── index.md
│   └── welcome.jpg
└── privacy.md

The “about” page is a page bundle. It logically associates a resource with content by bundling them together. Resources within a page bundle are page resources, accessible with the Resources method on the Page object.

Page bundles are either leaf bundles or branch bundles.

leaf bundle

A leaf bundle is a directory that contains an index.md file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.

branch bundle

A branch bundle is a directory that contains an _index.md file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without _index.md files are also branch bundles. This includes the home page.

Comparison

Page bundle characteristics vary by bundle type.

Files with resource type page include content written in Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode. In a leaf bundle, excluding the index file, these files are only accessible as page resources. In a branch bundle, these files are only accessible as content pages.

Leaf bundles

A leaf bundle is a directory that contains an index.md file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.

content/
├── about
│   └── index.md
├── posts
│   ├── my-post
│   │   ├── content-1.md
│   │   ├── content-2.md
│   │   ├── image-1.jpg
│   │   ├── image-2.png
│   │   └── index.md
│   └── my-other-post
│       └── index.md
└── another-section
    ├── foo.md
    └── not-a-leaf-bundle
        ├── bar.md
        └── another-leaf-bundle
            └── index.md

There are four leaf bundles in the example above:

about

This leaf bundle does not contain any page resources.

my-post

This leaf bundle contains an index file, two resources of resource type page, and two resources of resource type image.

• content-1, content-2

  These are resources of resource type page, accessible via the Resources method on the Page object. Hugo will not render these as individual pages.

• image-1, image-2

  These are resources of resource type image, accessible via the Resources method on the Page object

my-other-post

This leaf bundle does not contain any page resources.

another-leaf-bundle

This leaf bundle does not contain any page resources.

Branch bundles

A branch bundle is a directory that contains an _index.md file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without _index.md files are also branch bundles. This includes the home page.

content/
├── branch-bundle-1/
│   ├── _index.md
│   ├── content-1.md
│   ├── content-2.md
│   ├── image-1.jpg
│   └── image-2.png
├── branch-bundle-2/
│   ├── a-leaf-bundle/
│   │   └── index.md
│   └── _index.md
└── _index.md

There are three branch bundles in the example above:

home page

This branch bundle contains an index file, two descendant branch bundles, and no resources.

branch-bundle-1

This branch bundle contains an index file, two resources of resource type page, and two resources of resource type image.

branch-bundle-2

This branch bundle contains an index file and a leaf bundle.

Headless bundles

Use build options in front matter to create an unpublished leaf or branch bundle whose content and resources you can include in other pages.