ii.com: Introduction to Hugo Bundles🎁

Prerequisites

This article assumes that you know how to use Hugo to generate web pages from source files that are not bundles. One way to learn about this is in Infinite Ink’s Hugo Tutorial: Themeless & Gitless Introduction to Hugo. Here is part of that tutorial’s content directory, along with some Hugo terminology:

TGIH/content .Kind^[1] Also Known As

TGIH/content	.Kind^[1]	Also Known As
`/`	home	List Page
`/about.md`	page	Regular Page
`/articles/`	section	List Page
`/articles/one.md`	page	Regular Page

/

home

List Page

/about.md

page

Regular Page

/articles/

section

List Page

/articles/one.md

page

Regular Page

Note that…

Infinite Ink’s Hugo Tutorial uses a project directory named TGIH.
None of the TGIH content files and directories are bundles.
Some TGIH content files and directories are converted to bundles in the examples below.
Since Hugo v0.18, which was released 2016-December-19, “every piece of content is a Page.”

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.

ℹ

The file extension of index and _index can be any of the 13 content file extensions that are known to Hugo (.ad, .adoc, .asciidoc, .htm, .html, .markdown, .md, .mdown, .mmark, .pdc, .pandoc, .org, or .rst).
A leaf bundle is also known as a single page or a Regular Page.
A branch bundle is also known as a List Page.

Leaf bundle examples

Step 17.4^[2] in Infinite Ink’s Hugo Tutorial discusses the transformation of some TGIH^[3] 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/)^[4]	ii.com/about/	ii.com/articles/one/

An equivalent alternative is to replace about.md with about/index.md and replace 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/)^[4]	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 in Infinite Ink’s Hugo Tutorial, I wrote about adding content to the TGIH home page, which is a List 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 (essentially empty in this case) and Markdown content for the home 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/)^[4]	ii.com/

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

Bundle tip

💡

Here are some metaphors that I use to remember the meanings of _index.extension and index.extension.

I imagine the leading underscore (_) as one or more of the following.

a doorway or portal that allows Hugo to enter and process any child page — either a Regular Page or a List Page — within this directory🚪
a tree branch or plant 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 a List Page

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 Regular Page, which is also known as a leaf bundle🍃.

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

1. .Kind is a Hugo page variable and some of the possible values of this variable — for example “term” — changed in Hugo v0.73.0. Infinite Ink documents the v0.73.0+ kinds.

2. Step 17.4 is also available as a standalone page at Hugo Source Files, Destination Files, and Pretty URLs (thanks to AsciiDoc includes).

3. The website that is created in Infinite Ink’s Hugo Tutorial uses a project root directory named TGIH (for Themeless & Gitless Introduction to Hugo).

4. This is the URL if the output of the hugo config command includes uglyURLs: false, which is the default, and baseURL: ii.com/.

Introduction to Hugo Bundles🎁

Prerequisites

What is a Hugo bundle?

Leaf bundle examples

Branch bundle example

Bundle tip

Bundle references

Related pages

Endnotes

Edit this page 📝