Hugo index.md vs _index.md

What are Bundles in Hugo and how do index.md and _index.md fit in?

Seann Hicks

Seann Hicks

Wednesday, October 14, 2020

Hugo Branch Bundles and Leaf Bundles

There are 2 different types of bundles in Hugo, branch bundles and leaf bundles.  A Bundle is simply a collection of files that are pulled together to create a page in your web site.

Most web sites have a few one off pages, like a privacy page or an about page.  The Hugo static web site generator allows you to create these single pages using what Hugo calls leaf bundles. Single pages use the "index.md" file for front matter and page content. 

Hugo also allows you to create sets of pages that share common front matter. These sets are called branch bundles.  Branch bundles use the "_index.md" as a template to create the content leaf pages that hang off the branch.

_index.md and branch bundles

Hugo Branch Bundles direct the Hugo template engine to start a branch from the current folder. A Branch bundle invokes the list template to create a list page and a set of child leaf pages. Branch bundles are typically used where a set of multiple, similar pages is required. Like blog posts or documents on a specific subject.

Hugo branch bundles and render output

When you use the command to create a new leaf page in a branch bundle, like so:

hugo new post-1.md

Hugo uses the _index.md as a template to create the new post file. There is no index.md file in this scenario.  When the site is rendered, Hugo takes the file name "post-1.md" and generates a folder for it with the same name.  Then it creates an index.html file within that folder and runs the post-1.md file through the *single.html* template to generate the html.

An index.html file is also generated in the *posts* folder, but it's html content is generated using the list.html template in the theme.

index.md and leaf bundles

Most sites have content pages like privacy policies and about pages. Hugo leaf bundles work well for these page types.

Hugo Leaf Bundle with rendered output structure

Leaf bundles are quite simple.  Markdown content is processed using the single.html template to create an index.html content page. The Hugo renderer creates the same folder as the lead folder and simple converts the index.md file to a index.html file using the template engine.

Summary

The _index.md is a template to create specific markdown content files. It resides in a folder that forms a branch for multiple leaf pages. The index.md file is used for single pages.

The Hugo documentation is a bit vague on these differences, so hopefully this helps clear up any confusion.

Additional Resources

Some of my other articles on Hugo include:

If you are interested in learning more about static site generators like HUGO, I recommend the book "Working with Static Sites" by Raymond Camden and Brian Rinaldi. This book gives a good introduction to Harp.js, Jekyll, and Hugo.

Photo by Jamie Street on Unsplash

Sign-up to receive the weekly post in your inbox. I don't share email addresses, unsubscribe at any time.

Email Address