Clone: git clone https://github.com/CloudCannon/hugo-learn-blog-template.git
Starter branch: git checkout shortcode-bundles-intro-start
Finished lesson: git checkout shortcode-bundles-intro-finish
About page bundles and shortcodes
How to set up page bundles
How to use shortcodes
How to create your own shortcodes
Page bundles and shortcodes are great ways to manage your content pages. Both are reasonably simple to use at a basic level and can work well together, so we’ll use both of them in this lesson.
A great feature of Hugo is the ability to group together any resources related to your content pages. Normally, we would add, for example, all images to the
assets folder (depending on processing needs). But with page bundles, we can add images or other files to the same folder (or as a subfolder) as our content pages, which can make management easier and more convenient.
In Hugo, there are two types of page bundle. The difference is whether you add an
_index.md (note the underscore) file:
index.mdmeans that our content is a “leaf”. This means the content isn’t a section of its own and doesn’t have more content sections below it.
_index.mdmeans this content is a “branch” (i.e., more content directories below it), and lets Hugo know this is a
section. This file can also have metadata - note the
content/_index.mdfile with metadata for our index page.
A shortcode is a bit like a partial, except you can only use them in your content (and partials can only be used in your layouts). They are great for two reasons:
Better still, Hugo even has many built-in shortcodes, such as for Twitter and YouTube content, so you might not even have to create your own!
Create a page bundle
As usual, feel free to clone the code for this lesson.
In a previous lesson, we created some basic blog posts for displaying, using files in the
static folder as resources. These are fine as is, but we can also group content as page bundles, where images and other resources are local to the content.
Why is this useful? It makes it easier to manage/keep track of resources specific to a page, and you can also add metadata about the page/content, such as description and alt text.
For an example bundle, we’ll create a gallery page showing some of our native birds. To begin creating a bundle, use the Hugo CLI to create a new
gallery folder with an
Next, move the
images folder from
content/gallery, and then add this front matter to
gallery/index.md, with metadata such as references to our local
With page bundles, you can also directly use page resources in a template, without needing to add this front matter metadata. However, this metadata gives us the flexibility to create shortcodes using alt/description text along with the relative URL of the image.
Using shortcodes in Hugo is very easy.
In most cases, all you need to do is use the name of the shortcode inside of your content, with any necessary parameters and slightly different syntax than usual. Feel free to add these examples to
content/gallery/index.md to see how they turn out:
Some shortcodes, such as
highlight, also allow nesting of content to be parsed/rendered:
We’ve set up a page bundle with a folder of images and metadata about the images to our
index.md front matter. While we could use Go templating inside a layout (
gallery/index.md will default to using
_default/single.html) to display these images, this is a good opportunity to create our own (very basic) shortcode that could be set up in any similar page bundle.
Because we have a group of images, let’s create a flexible (but slightly contrived) gallery shortcode:
shortcodes/gallery.htmlwith the following content:
We are using a new function called .Get, which is specific to shortcodes and allows us to get parameter data from our shortcode (either as numbered or named parameters). We are looking for a “figures” parameter in our shortcode, so if it’s true/exists, we’ll render our page bundle images as figures with captions; if not, we’ll just render them as images.
If we navigate to our
/gallery page, we should see two galleries rendered on our page - one containing figures, and another without.
There’s a lot more you can do with your own shortcodes, such as nesting content, error handling, and more, but that is beyond the scope of this lesson. See Hugo’s docs for custom shortcodes for more!
With page bundles and shortcodes, we have more options for managing and displaying our page content.
For this and other pages, we’ve used front matter, which gives us access to local data for a page. However, there are times when we might want to reuse data throughout the site, like you might expect from a database. Fortunately, Hugo allows this, so global data files is our next subject.