05 – Basic Content Organization
In the previous lesson, we learned how to make Hello World in Hugo. Let’s expand on that simple example to add some structure to our website and learn how to organize content in a more useful way.
Tweaking our template
Before we go any further, let’s take a minute to revisit our minimalist template and improve the presentation a little. Open your layouts/_default/single.html page and change the content to this:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/skeleton/2.0.4/skeleton.min.css">
</head>
<body>
<main class="container">
<h1>{{ .Title }}</h1>
{{ .Content }}
</main>
</body>
</html>
We’re including a CSS boilerplate called Skeleton to add a little style to our page. It’s a tiny file that is less than 2 kB gzipped, so it adds little weight to our tutorial pages. You can read about Skeleton here: https://github.com/dhg/Skeleton
Adding a couple more content examples
The Hello World example placed a content file at the root directory of the website, but that’s not usually how a website is structured. Let’s instead create a website with articles about pets. We’re going to have two sections for cats and dogs.
Execute these commands to create two new files:
hugo new cats/siamese/index.md
hugo new dogs/terrier/index.md
When you’re done, your content directory will look like this:
.
├── cats
│ └── siamese
│ └── index.md
├── dogs
│ └── terrier
│ └── index.md
└── hello-world.md
If you run hugo server -D now, you’ll see your new pages available at http://localhost:1313/cats/siamese/ and http://localhost:1313/dogs/terrier/.
Let’s a little more content to our pages so that we have something to work with. We’ll borrow a little text from Wikipedia
Edit the Siamese cat article:
---
title: "All About Siamese Cats"
date: 2022-04-02T14:03:21-04:00
draft: false
---
The Siamese cat is one of the first distinctly recognized breeds of Asian cat. Derived from the Wichianmat landrace, one of several varieties of cat native to Thailand (formerly known as Siam), the original Siamese became one of the most popular breeds in Europe and North America in the 19th century.
The carefully refined, more extreme-featured, modern-style Siamese is characterized by blue almond-shaped eyes; a triangular head shape; large ears; an elongated, slender, and muscular body; and various forms of point colouration.
And the Terrier article:
---
title: "All About Terriers"
date: 2022-04-02T14:08:36-04:00
draft: false
---
Terrier (from Medieval Latin terrarius (“of earth”) from Latin terra (“earth”)) is a type of dog originally bred to hunt vermin. A terrier is a dog of any one of many breeds or landraces of the terrier type, which are typically small, wiry, game, and fearless.
Terrier breeds vary greatly in size from just 1 kg (2 lb) to over 60 kg (132 lb, e.g. Black Russian Terrier) and are usually categorized by size or function. There are five different groups of terrier, with each group having different shapes and sizes.
Now we have a little more content to work with. This will come in handy as we elaborate on our templates later.
Organizing content into categories: sections and leaf bundles
In our Hello World lesson, we executed hugo new hello-world.md to create our file at the root directory of our website.
In this tutorial, we instead created our Markdown files under cats and dogs folders. In Hugo lingo, the first level of folders in the content folder are known as Sections.
For most Hugo projects, Sections are the primary way in which content will be organized. While there are other methods available - especially Taxonomies - Sections are the most natural approach because they correspond to folders in your content directory and are visible in the URL of your pages.
In addition to our cats and dogs sections, the other thing to notice about the examples in this lession is that instead of specifying a file name like hello-world.md, we instead named our folders terrier and siamese and placed the content in index.md files.
We could have also created files with a path of content/terrier.md and content/siamese.md, but using folders has the important advantage of being able to keep related assets, such as images, alongside our Markdown files.
Folders that contain content with an index.md file are known as Leaf Bundles. They’re called leaf bundles because they can’t contain other bundles - they are the end of the branch.
Using Sections
You can think of sections as the main way to categorize your site content. You might have a simple site with only one section - maybe titled “articles” - or extensive content with dozens of sections.
In any case, the basic rule is that sections can contain either markdown files or bundles. Unless you have text-only articles, you’ll probably want to use bundles.
You can access the name of the sec†ion in your template by using the .Section variable. Let’s update our single.html template to see this in action.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/skeleton/2.0.4/skeleton.min.css">
<style>
header {
background-color: #333;
color:white;
margin:1rem 0;
padding: 1rem;
}
</style>
</head>
<body>
<main class="container">
<header>
Section: <strong>{{ .Section }}</strong>
</header>
<h1>{{ .Title }}</h1>
{{ .Content }}
</main>
</body>
</html>
We’ve added a <header> element to our template file and dressed it up with a little bit of CSS. Here’s what our Terrier page looks like now:
Using leaf bundles
For most sites, content pages consist of text along with supporting assets such as images, videos, and downloadable files.
In Hugo, you could dump all of these in the static folder, but that would quickly get unmanageable. Instead, the better approach is to keep them in the same folder as your Markdown file.
Folders that contain Markdown and other assets are known as leaf bundles. Leaf refers to the limitation that leaf bundles can’t contain other bundles - a leaf is something at the end of a branch. There is another type of bundle known as a branch bundle that contains other bundles. We’ll cover that in a later section.
Assets in your leaf bundle can exist at the top-level of the folder, or be contained within another folder.
This is an acceptable way to place a jpeg of a cat in our leaf bundle:
.
├── index.md
└── siamese-cat-photo.jpg
… and this in another good way:
.
├── images
│ └── siamese-cat-photo.jpg
└── index.md
Both methods are fine, so choose the one that works best for you.
Referencing assets in leaf bundles
When you’ve added assets in a leaf bundle, you can reference them using relative paths. Add this line of Markdown code to your Siamese cat index.md file:
