Migration from single content files to Hugo page bundles

By admin
Since I migrated from

Jekyll
PERSON

to

Hugo
EVENT


a few years ago
DATE

, I have never looked at any other static site generator. I elaborated on this process in “

From Jekyll to Hugo
WORK_OF_ART

! From GitHub Pages to Netlify!”. It may not be the easiest tool of its kind out there, but the complexity pays off in the form of flexibility, speed, and reliability.

Over

the last few years
DATE

, I have been writing and adding more

Markdown
ORG

files to the content pile, as well as images to the static resources folder. It was all good, but I wasn’t fully utilizing the potential of

Hugo
EVENT

. Finally, I decided to migrate from individual

Markdown
PERSON

files to

Hugo
EVENT

page bundles. For those unfamiliar with this concept, the following simple diagram should help.

// BEFORE . ├── content │


PERSON

── posts │


PERSON

──

2023-10-04-post-one.md
CARDINAL

│ └──

2023-10-05-post-two.md └──
PERSON

static ├──

post-one-pic-1.jpg
NORP

├── post-one-pic-2.jpg ├──

post-two-pic-1.jpg └──
PERSON

post-two-pic-2.jpg // AFTER . └── content


PERSON

── posts


PERSON

──

2023-10-04
DATE

-post-one │ ├── index.md │ ├──

post-one-pic-1.jpg
NORP

│ └── post-one-pic-2.jpg └──

2023-10-05
DATE

-post-two ├── index.md ├──

post-two-pic-1.jpg └──
PERSON

post-two-pic-2.jpg

Benefits of Page Bundles

The obvious benefit is file colocation. All files related to a single post live in the same directory. It vastly eliminates the potential for orphaned static files. When you delete a draft that you’ve lost hope for (which happens to me all the time), all related files will also be deleted. And because all links to images follow real relative paths,

Markdown
PERSON

previews finally render correctly. A nice bonus!

Page resources is a

Hugo
EVENT

concept where all files in a page bundle are accessible in a template via {{ .Resources }} . They also have some extra image processing powers that are impossible with static files. This is very powerful and has allowed me to massively simplify how I handle multiple file formats ( jpg , webp , and avif ) and dark mode variations. I have also managed to eliminate some unnecessary logic for handling open graph images—I need to remember to include an og.jpg file in the page bundle, and

Hugo
EVENT

will take care of the rest.

This single change doesn’t look like a lot to the visitor, but it was a massive improvement for me as a publisher. I can also reveal that I am planning to translate some of my posts into

Polish
NORP

, and with page bundles, it will be a breeze.

If you’re curious about how it works, the source code for my website is available on GitHub. Shout out if you have any questions or suggestions. Peace ✌️

Did you like it? Please share it with your friends or get me a beer coffee. Thanks! Buy me a coffee All done 👌