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.