Introduction to Hugo Bundles⁠🎁

Page contents

Prerequisites

This article assumes that you know how to use Hugo to generate web pages from unbundled source files. One way to learn about that is in Infinite Ink’s Hugo Tutorial: Themeless & Gitless Introduction to Hugo.

Note that the Hugo Tutorial uses a project root directory named TGIH (for Themeless & Gitless Introduction to Hugo) and some of these TGIH files are used in the examples below.

What is a Hugo bundle?

A source file below the content/ directory named either index.md or _index.md means that hugo will generate the destination file(s) from some or all of the files in a directory. When index.md is used, the containing directory is called a leaf bundle and when _index.md is used, the containing directory is called a branch bundle.

Leaf bundle examples

Step 17.4 Source files, destination files, and pretty URLs[1] in Infinite Ink’s Hugo Tutorial discusses the transformation of some TGIH[2] files from source to destination to URL (viewable in a web browser after deployment). Here is a modified version of that transformation table.

Transformation of non-bundles

source in
TGIH/content/

about.md

articles/one.md

destination in
TGIH/public/

about/index.html

articles/one/index.html

URL (if baseURL
is ii.com/)[3]

ii.com/about/

ii.com/articles/one/

An equivalent alternative is to replace about.md with about/index.md and articles/one.md with articles/one/index.md. The transformations then looks like this:

Transformation of leaf bundles

source in
TGIH/content/

about/index.md

articles/one/index.md

destination in
TGIH/public/

about/index.html

articles/one/index.html

URL (if baseURL
is ii.com/)[3]

ii.com/about/

ii.com/articles/one/

With this structure, the source directories content/about/ and content/articles/one/ are each a leaf bundle.

 

Branch bundle example

In step 15. Explore the layouts directory in Infinite Ink’s Hugo Tutorial, I wrote about adding content to the home web page by adding the following highlighted HTML paragraph to the home.html layout file.

<h1 class="title">{{ .Title }}</h1>

<p>
Here are the articles on this website <strong>ordered by publication date</strong>, starting with the most recently published article.
</p>

 

An alternative is to put the following highlighted line in home.html.

<h1 class="title">{{ .Title }}</h1>

{{ .Content }}

 

And create content/_index.md that contains the following.

---
# front matter, possibly empty, is required
---

Here are the articles on this website **ordered by publication date**, starting with the most recently published article.

 

The content/ directory is an example of a branch bundle and this content/_index.md file contains metadata (empty in this case) and Markdown content for the home web page. The transformation will look like this:

Transformation of a branch bundle

source in
TGIH/content/

_index.md

destination in
TGIH/public/

index.html

URL (if baseURL
is ii.com/)[3]

ii.com/

Note that if this _index.md file does not exist, the home page is created from the TGIH[2] layouts/_default/home.html layout file, which references some config.yaml settings (such as title).

Bundle references and tips

For more about Hugo bundles, see:

 

💡︎

Here’s a mnemonic that I use to remember the meaning of _index.extension: I think of the leading underscore (_) as one or more of the following.

  • a doorway or portal that allows Hugo to enter and process any child bundle within this directory

  • a plant or tree branch that may comprise multiple leaves and/or multiple sub-branches⁠🌿

  • a fragment of capital letter L, which reminds me that _index is used for List-type pages

I remember the meaning of index.extension by noting that there is no doorway or branch (i.e., no _) and Hugo will process this directory as a leaf🍃.

Request:  Is this tip useful to you? Whether it is or isn’t, I’d love to hear your thoughts about it because sometimes I wonder if anyone understands the way I’m thinking about something‽

Endnotes


1. Step 17.4 in Infinite Ink’s Hugo tutorial is also available as a standalone page at Hugo Source Files, Destination Files, and Pretty URLs (thanks to AsciiDoc includes).
2. The website that is created in Infinite Ink’s Hugo Tutorial uses a project root directory named TGIH (for Themeless & Gitless Introduction to Hugo).
3. This is the URL if the output of the hugo config command includes uglyURLs: false, which is the default, and baseURL: ii.com/.

Edit this page👍👎✍

To add a reaction or comment to this page, you need a GitHub account and your browser needs to be able to run a script that is hosted at https://utteranc.es.