Using Hugo page bundles
You can opt-in to using page bundles in Hugo Clarity with
usePageBundles in your site configuration or in a page's front matter. Read more about
With page bundles, resources for a page or section, like images or attached files, live in the same directory as the content itself rather than in your
Hugo Clarity supports the use of leaf bundles, which are any directories within the
content directory that contain an
index.md file. Hugo's documentation gives this example:
1content 2├── about 3│ ├── index.md 4├── posts 5│ ├── my-post 6│ │ ├── content1.md 7│ │ ├── content2.md 8│ │ ├── image1.jpg 9│ │ ├── image2.png 10│ │ └── index.md 11│ └── my-other-post 12│ └── index.md 13│ 14└── another-section 15 ├── .. 16 └── not-a-leaf-bundle 17 ├── .. 18 └── another-leaf-bundle 19 └── index.md
In the above example `content` directory, there are four leaf bundles:
about: This leaf bundle is at the root level (directly under
contentdirectory) and has only the
my-post: This leaf bundle has the
index.md, two other content Markdown files and two image files. image1 is a page resource of
my-postand only available in
my-post/index.mdresources. image2 is a page resource of
my-postand only available in
my-other-post: This leaf bundle has only the
another-leaf-bundle: This leaf bundle is nested under couple of directories. This bundle also has only the
The hierarchy depth at which a leaf bundle is created does not matter, as long as it is not inside another leaf bundle.
Advantages to using page bundles
The image below is part of the bundle of this page, and is located at
content/post/bundle/building.png. Because it's within this page's bundle, the markup for the image only has to specify the image's filename,
If you ever change the name of the directory in which this Markdown file and the image reside, the reference to the image would not need to be updated.
In addition to more cleanly organizing your content and related assets, when using page bundles, Hugo Clarity will automatically generate markup for modern image formats, which are smaller in file size.
For instance, when you reference an image like
building.png, Hugo Clarity will check to see if the same image (based on filename) exists in WebP, AVIF or JXL formats. If you inspect the image above, you'll see a
<source> element for
building.webp, because that file is also present. Hugo Clarity will only include the markup if these images exist.
Finally, note that page assets can be further managed and refined within the page's front matter if you wish, and are not limited to images alone.
Disadvantages to using page bundles
Page resources in a bundle are only available to the page with which they are bundled — that means you can't include an image with one page and then reference it from another.
Images that are being used in multiple places are more appropriate for your Hugo
assets directory. Unlike files in the Hugo
static directory, files in the
assets directory can be run through Hugo Pipes, which includes image processing.