Dynamic Content Lists with Partials

The Challenge: Escaping the Local Context

Our hero banner partial was simple: it received a chunk of data (the context) and displayed it. But how do we build a partial that shows the "3 Latest Blog Posts"? The information about those posts isn't in our homepage.json file; it lives in the content/blog/ directory.

The . (dot) in a Hugo template refers to the current context. When our index.html dispatcher calls a partial for a homepage section, the . is the data for that specific section. How can the partial "see" outside this context to find the blog posts?

This is a common challenge, and solving it is key to unlocking Hugo's power. The solution lies in using Hugo's global variables.

Step 1: Accessing Global Content with .Site.Pages

Hugo provides a global variable, .Site.Pages, which is an array of all pages on your entire website. By using .Site.Pages instead of .Pages or .Data.Pages (which are context-dependent), a partial can access any piece of content from anywhere on the site, regardless of where the partial is being rendered.

This forum discussion provides a perfect, real-world example of a developer facing this exact problem.

As you saw in the forum thread, the key is to switch from a context-specific variable like .Data.Pages to the global .Site.Pages. This gives our partial the superpower to see the entire site.

Step 2: Filtering and Slicing the Content

Now that we can access all pages, we need to narrow them down. For a "Latest Blog Posts" section, we need to perform three steps:

1. Filter the pages to only include those in the blog section.
2. Sort them by date (implicitly, Hugo's default sort is usually sufficient, but explicit sorting is also possible).
3. Limit the list to a specific number, like the 3 most recent posts.

Hugo provides powerful template functions to do this in a single line. The main ones we'll use are where, first, and range.

• range: This function iterates, or loops, over a list of items. We'll use it to create an <li> for each blog post.
• where: This function filters a list. We'll use it like this: where .Site.Pages "Section" "blog". This command takes the list of all site pages and returns only those where the Section parameter is equal to "blog".
• first: This function slices a list, returning only the first N items. For example, first 3 ... will give us the three most recent posts.

To see the range function in action, you can review this quick video.

By combining these functions, we create a "pipeline." We get all the pages, filter them by section, take the first few, and then loop over that final list. The code from the forum post you read sums it up perfectly: {{ range first 10 (where .Site.Pages "Section" "blog") }}.

Step 3: Vibe Coding the "Latest Posts" Partial

Let's apply this knowledge. First, we need an entry in our data/homepage.json to tell the dispatcher to render this new partial.

data/homepage.json (new entry)

{
  "id": "latest-news",
  "type": "latest-posts",
  "title": "Latest From The Blog",
  "section": "blog",
  "limit": 3
}

This data structure is smart. It not only defines a title but also makes the partial reusable by allowing us to specify which section to pull from and how many items to limit. You could easily create another section for "Latest News" by just changing the section value.

Now, let's write the prompt for our AI assistant.

Prompt for AI:

I need you to generate a Hugo partial for a "latest posts" section. The file should be named latest-posts.html and be located in layouts/partials/homepage/.

Context:
The partial will receive a data object (.) with the following fields:

• .title: The heading for the section (e.g., "Latest From The Blog").
• .section: The content section to query (e.g., "blog").
• .limit: The maximum number of posts to display (e.g., 3).

Instructions:

1. Create an HTML <section> element as the main container.
2. Display the partial's .title in an <h2> tag.
3. Use Hugo's template functions to get the desired pages. The logic should be: first N pages (.limit) from the result of where .Site.RegularPages "Section" is .section.
4. Use the range function to loop through these pages.
5. Inside the loop, for each page, create a list item <li> inside a <ul>.
6. Each list item should contain an <a> link. The link's href must be the page's .Permalink and the link's text must be the page's .Title.
7. Below the title link, display the page's summary using {{ .Summary }}.
8. Use sensible default values for .limit (3) and .section ("blog") in case they are not provided. Use CSS classes for styling.

Note: I've specified .Site.RegularPages instead of .Site.Pages. This is a best practice, as RegularPages automatically excludes section pages, taxonomies, and other non-content pages, giving you a cleaner list to start with.

Step 4: Analyzing the AI-Generated Code

Here’s a likely output from the AI, which we can now analyze.

layouts/partials/homepage/latest-posts.html

{{/*
  This partial displays a list of the latest posts from a given section.
  Context expects: .title, .section, .limit
*/}}
<section class="latest-posts-section" id="{{ .id | default "latest-posts" }}">
  <div class="container">
    {{ with .title }}
      <h2 class="section-title">{{ . }}</h2>
    {{ end }}
    
    {{/* Define variables with default fallbacks */}}
    {{ $limit := .limit | default 3 }}
    {{ $section := .section | default "blog" }}

    {{/* Find the pages to display */}}
    {{ $pages_to_show := first $limit (where .Site.RegularPages "Section" $section) }}

    {{ if $pages_to_show }}
      <ul class="post-list">
        {{ range $pages_to_show }}
          <li class="post-item">
            <h3 class="post-title"><a href="{{ .Permalink }}">{{ .Title }}</a></h3>
            <p class="post-summary">{{ .Summary }}</p>
          </li>
        {{ end }}
      </ul>
    {{ else }}
      <p>No posts found in the '{{ $section }}' section.</p>
    {{ end }}
  </div>
</section>

Code Breakdown:

• Variables with Defaults: The lines {{ $limit := .limit | default 3 }} are excellent defensive programming. If our JSON doesn't specify a limit, it defaults to 3.
• The Pipeline: {{ $pages_to_show := first $limit (where .Site.RegularPages "Section" $section) }} is the heart of the partial. It perfectly executes our logic, storing the result in a variable for clarity.
• The range loop: The code iterates through $pages_to_show. Inside this loop, the context . now refers to the current page being processed, so we can access its properties like .Permalink, .Title, and .Summary.
• Conditional Rendering: The {{ if $pages_to_show }}...{{ else }}...{{ end }} block is another sign of quality code. It ensures the page doesn't break if no posts are found, and instead displays a helpful message.

Conclusion

Congratulations! You've just created your first dynamic content component. This partial is powerful because it's both reusable and aware of the site's overall content structure. You can now drop this partial anywhere on your site to feature content from any section, a technique at the heart of building complex, interconnected websites.

Key Takeaways:

• To access content from outside a partial's local context, use the global .Site.RegularPages variable.
• You can create powerful content queries by "pipelining" Hugo functions like where, first, and range.
• Designing partials to accept parameters (like section and limit) makes them incredibly flexible and reusable.
• Prompting an AI with clear logic (where...first...range) and data requirements results in high-quality, robust template code.

Preview of the next lesson:
We have now built both a static partial (hero banner) and a dynamic one (latest posts). Our homepage is starting to feel like a real website. In the next module, we'll address another fundamental piece of the puzzle: navigation. We'll kick off Module 6 by learning how to define a multi-level site menu and write a prompt to generate a partial that renders it, allowing users to navigate the complex site we're building.