index.md vs _index.md in Hugo

For years, 19ft.com has been a hand-built static HTML website with a smidgen of PHP to set things like dates and include a header and footer to each page. While I haven’t yet redesigned it, it seemed prudent to move it to a static site generator before I did so and I chose Hugo, mainly because as a go CLI app, it had no dependencies to worry about.

This is a really simple website with handful of top level pages and a couple of subpages, so is a good one to port. It also doesn’t have any lists of blog posts which seem to feature heavily in all documentation around static site generators.

Creating a page

To create a new page in Hugo, you add a file with front-matter to the content directory where the extension tells Hugo how to preprocess. That is /content/about.md will be a processed /public/about/index.html which is then uploaded to the web server.

index.md

Given what we know from the about.md example, you would assume that /content/index.md would be processed to /public/index.html and you’d be right.

What will suprise you though is that the about page has disappeared!

This is because of something called Page bundles. There are two types and you create a Leaf bundle if create an index.md file. The important thing about a leaf bundle is that the content from all sibling pages are available as page resources, not as pages in their own right.

If you want separate pages, then you need a Branch bundle.

_index.md

To create a branch bundle, you use _index.md for your index filename. When you do this, content/_index.md is processed to /public/index.html and the about page is also created as before.

This also works in subdirectores.

If you want a landing page in /products/ and also separate product pages at /products/product1, /products/product2, etc, then you can either:

• Create content/products.md along with content/products/product1.md
• Create content/products/_index.md along with content/products/product1.md

Fin

As I was porting an existing site, I didn’t use a theme and built my layouts directly, maybe that’s why I was tripped up but this index vs _index thing.

Or maybe I just didn’t read the right section of the docs and this is very obvious to everyone who uses Hugo.

I have a working site now, so I’m happy. Next steps are leveraging the power of Hugo to do more with it!