Section Content Listing Template

Understanding How Hugo Organizes Content into Lists

Before we can create a list page, we need to understand what Hugo considers a "list." In Hugo, content organization directly influences the site structure. When you create subdirectories inside your main content/ folder, Hugo automatically treats each of these as a section.

For example, a content structure like this:

content/
├── blog/
│   ├── post-1.md
│   └── post-2.md
└── services/
    ├── service-a.md
    └── service-b.md

...will automatically create two sections: blog and services. Hugo will then generate index pages for them at /blog/ and /services/. These are the list pages we want to customize.

By default, these pages are very basic. To make them useful, we need to create a custom template.

The Engine of Hugo Lists: The range Function

At the heart of every Hugo list page is the range function. If you have some familiarity with programming, you can think of range as Hugo's version of a for loop. It iterates over a collection of items (in our case, pages) and lets you do something with each item.

To list pages, we combine range with a page variable. The most important ones to know are:

• {{ .Site.Pages }}: A collection of all pages on your entire website.
• {{ .Pages }}: A context-aware collection. When used in a section's list template, it contains only the pages within that section.

For our goal of creating a section list page, {{ .Pages }} is precisely what we need.

A basic list template using range looks like this:

{{/* layouts/_default/section.html */}}
<h1>{{ .Title }}</h1>

{{ range .Pages }}
  <article>
    <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
  </article>
{{ end }}

This code snippet does the following:

1. Prints the section's title (e.g., "Blog").
2. Starts a loop through every page within that section (range .Pages).
3. For each page, it creates an <article> block containing a linked title.
   • .Permalink is the page's URL.
   • .Title is the page's title from its front matter.

Crafting the AI Prompt for a List Page

Now that you understand the Hugo concepts, we can translate them into an effective AI prompt. We won't just ask the AI to "make a blog list." We'll provide specific, structured instructions, leveraging the prompt engineering principles you're becoming familiar with.

A good prompt gives the AI Context, a clear Task, and specific Instructions.

Let's apply this to generate our list page template.

The "Vibe Coding" Walkthrough

Imagine we have a content/blog/ section and we want to create its list page.

1. Define the Goal: We need a template that will render the page at /blog/. Based on Hugo's template lookup order, a good place for this is layouts/_default/section.html. This file will serve as the default template for any section list.

2. Formulate the Prompt: We will craft a prompt that is simple, specific, and short, as recommended by prompt engineering best practices.

Here is a well-structured prompt based on these principles:

Prompt:

I am building a website with Hugo. I need to create a list page template for my content sections.

Task: Generate the HTML code for a Hugo template file named section.html that will be placed in layouts/_default/.

Instructions:

1. The template should be wrapped in a <main> HTML5 tag.
2. Display the section's title in an <h1> tag. Use the Hugo variable {{ .Title }}.
3. Use Hugo's range .Pages function to loop through all pages in the current section.
4. Inside the loop, for each page, create an <article> with the class post-preview.
5. Inside each article, include:
   • An <h2> containing a link to the page (.Permalink) with the page's title (.Title) as the text.
   • A <p> tag displaying the page's summary (.Summary).

3. Analyze the Expected Output: The AI should return code that looks very similar to this:

   <main>
     <h1>{{ .Title }}</h1>
     {{ range .Pages }}
       <article class="post-preview">
         <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
         <p>{{ .Summary }}</p>
       </article>
     {{ end }}
   </main>
   

This code is ready to be placed in layouts/_default/section.html. Once saved, Hugo's development server will automatically pick it up, and when you navigate to /blog/, you will see a neatly formatted list of your posts. You can then use the design adaptation skills from the previous lesson to style the .post-preview class.

Conclusion

You have now learned one of the most powerful and common patterns in Hugo development: listing content. By combining your understanding of Hugo's sections and the range function with structured AI prompting, you can quickly generate the backbone of any content-driven website.

Key Takeaways:

• Hugo organizes content in content/ subdirectories into sections, each getting an automatic index page.
• The range .Pages function is the primary tool for iterating over a section's content within a list template (section.html or list.html).
• An effective AI prompt for a list page clearly specifies the context (Hugo, template file), the task (generate code), and the instructions (what variables and HTML tags to use).

Preview of the next lesson:
Our new list page works perfectly, but what happens when you have hundreds of blog posts? Displaying them all at once would be impractical. In the next lesson, we will solve this by learning how to implement pagination on a list page using Hugo's built-in Paginator object.