List-Templates

Right, so you’ve got a list of pages. A big, flat, boring list. Hugo’s default range is great for a simple blog roll, but let’s be honest, most sites need a bit more structure. You don’t just dump every single product or article on one page and call it a day. You want to group them, organize them, make sense of the chaos. That’s where these grouping functions come in. They are the unsung heroes of making your Hugo site look like it was designed by a thoughtful human and not a spreadsheet macro.

Now, let’s talk about pagination. You didn’t think you’d just dump 10,000 blog posts onto a single page, did you? Your server would burst into flames, your users would flee, and Google would personally send a strongly worded letter. Pagination is the art of slicing that massive content salami into manageable, bite-sized pieces. Hugo handles this with a trio of concepts: the paginate setting, the .Paginator object, and the paginator template. It’s powerful, but it has a few… idiosyncrasies.

Right, so you’ve got your terms set up and your content tagged. Now comes the fun part: actually showing off that curated list of content on the taxonomy term page. This is Hugo’s way of saying, “Hey, you asked for all the pages tagged ‘banana-bread’, here they are.” It’s a powerful concept, but the default template can feel a little… sparse. Let’s fix that. The magic happens in a template file at /layouts/_default/taxonomy.html. If that doesn’t exist, Hugo falls back to its internal default, which is about as exciting as plain toast. We’re going to make banana bread toast. The Core Loop: .Pages Inside your taxonomy.html, the most important variable is .Pages. This is a collection of all the pages that have this specific term. Your job is to range over them and display what you need. <!-- layouts/_default/taxonomy.html --> <main> <h1>Posts about {{ .Title }}</h1> <p>Here you'll find all {{ len .Pages }} of my brilliant thoughts on {{ .Title }}.</p> <ul> {{ range .Pages }} <li> <article> <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> <time datetime="{{ .Date.Format "2006-01-02" }}">{{ .Date.Format "January 2, 2006" }}</time> <p>{{ .Summary }}</p> </article> </li> {{ end }} </ul> </main> Why .Title and not something like .Data.Term? Because the .Title of the taxonomy page is the term, nicely capitalized. Hugo’s doing you a solid. The .Data family ({.Data.Term}, {.Data.Plural}}) is still there if you need it, but .Title is cleaner for this purpose. Pagination: Because Your “Recipes” Tag Might Blow the Stack If you have a popular term with hundreds of pages, dumping them all into a single HTML page is a performance nightmare. We need pagination. This is where Hugo’s built-in paginator shines. We don’t use .Pages directly; we hand the collection off to the paginator. <!-- layouts/_default/taxonomy.html --> {{ $paginator := .Paginate .Pages }} <main> <h1>Posts about {{ .Title }}</h1> {{ range $paginator.Pages }} <!-- Your article rendering code from above --> {{ end }} <!-- This next part is non-negotiable --> {{ template "_internal/pagination.html" . }} </main> The _internal/pagination.html template is Hugo’s gift to you—it generates sensible “Previous / Page 2 / Next” links. You can absolutely create a custom pagination.html template if you want it to match your site’s style, but for getting started, the internal one is a lifesaver. The Summary Gotcha Notice I used .Summary in the first example. It’s convenient, but it’s also a trap. Hugo generates the summary by either taking the first 70 words of your content or everything before a manually inserted `

Alright, let’s talk about rendering all your terms on a single taxonomy list page. This is Hugo’s way of giving you a directory of all the tags, categories, or any custom taxonomy you’ve dreamed up. It’s a simple concept, but as usual, the devil is in the details, and Hugo’s approach here is… well, let’s call it idiosyncratic. The first thing you need to know is that Hugo doesn’t just automatically create a page for this. You have to tell it you want one. You do this by creating a template file with a very specific name. The format is layouts/[TAXONOMY]/list.html. So, for your garden-variety tags, you’d create layouts/tags/list.html. For a custom taxonomy like manufacturers, it would be layouts/manufacturers/list.html.

Right, let’s talk about the beating heart of your Hugo site’s content engine: layouts/_default/list.html. This isn’t just a template; it’s the template Hugo reaches for by default when it can’t find a more specific one. It’s the workhorse. It’s the one you’ll be wrestling with the most, so we’d better get to know it intimately. Think of it this way: any time you ask Hugo to show you a group of something—all your blog posts, all the projects in your “Web Development” category, all the items tagged “golang”—it’s going to try to use this template. Its job is to take a list of pages (the .Pages or .RegularPages variable) and render them. The logic is simple: range through the pages and do something with each one. But the devil, as always, is in the details.

Alright, let’s talk about the home page. This is your digital front door, the first thing most people will see. And because of that, Hugo, in its infinite wisdom, gives you a few ways to build it, which is both a blessing and a curse. The main event is layouts/index.html. This file sits at the root of your layouts directory and is the default template for when someone hits the root of your domain (yoursite.com/).

Alright, let’s get our hands dirty with .Pages and .RegularPages. If you’re here, you’ve probably realized that Hugo’s idea of a “page” is a bit more expansive than yours. You think of a page as, well, a page. Hugo sees a page as any content-bearing node in its site structure. This distinction is the entire reason these two variables exist, and understanding it will save you from a world of head-scratching moments.