How to Add Related Articles in Hugo

Adding related content is a great way to boost reader engagement on your Hugo-powered site. With Hugo’s built-in related content engine, you can show contextually relevant posts with minimal setup. Here’s a thorough, step-by-step guide, including additional tips you may have missed.

1. Configure hugo.toml

First, you need to define how Hugo should identify related content. Add or update the [related] section in your hugo.toml (or config.toml). Here’s an example that considers tags, keywords, and date—adjust weights to fit your content:

[related]
includeNewer = true   # Include newer posts than the current one
threshold = 80        # Relevance threshold (0-100)
toLower = false

[[related.indices]]
name = "tags"
weight = 80

[[related.indices]]
name = "keywords"
weight = 100

[[related.indices]]
name = "date"
weight = 10

Note: If you add a [related] section, you must include all indices you need; Hugo will not supplement with defaults if any are missing. Also, Hugo supports hugo.toml or config.toml, the naming depends on your project’s Hugo version.

Extra Tips:

• If you want to narrow the date range (e.g., by year or month), add pattern = “2006-01” to the date index.
• For best results, ensure your content front matter contains the relevant fields (i.e., tags, keywords, etc.).

2. Add Front Matter for Posts

For related content to work, the posts themselves must have consistent front matter fields corresponding to your indices. For instance:

---
title: "Introduction to Hugo"
date: 2025-08-01
tags: ["hugo", "static site"]
keywords: ["hugo", "static", "blog"]
---

Adjust to TOML or JSON to match your preference.

3. Create layouts/partials/related.html

Next, add a partial template that renders the related articles, such as layouts/partials/related.html:

{{ $related := .Site.RegularPages.Related . | first 5 }}
{{ with $related }}
<h3>Related Posts</h3>
<ul>
    {{ range . }}
        <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
    {{ end }}
</ul>
{{ end }}

You can adjust the number (e.g., first 5) as you like.

4. Include the Partial in Your Post Template

Insert the related articles partial into your main content template, usually layouts/_default/single.html, at the place you want related articles to appear:

{{ partial "related.html" . }}

This will ensure the list displays at the end of every single post.

5. (Optional) Customize and Test the Output

• You can further customize the list’s appearance or logic in related.html.
• Test on several posts to ensure related articles are shown. If nothing appears, double-check your content front matter and configuration.
• If you use a theme, check whether it includes a related posts partial already—if so, you may need to override it with your custom layouts/partials/related.html.
• Hugo does not index content text—only front matter parameters are considered by the relation engine.

6. (Optional) Advanced Usage

• Use additional indices like title or description if relevant.
• You can add fragment-based matching (matching by headings within posts) for more advanced use-cases, but this is not needed for most blogs.
• For multi-language sites, place related config inside language-specific config files if needed.

Known Pitfalls and Troubleshooting

• Be sure every post you want related content on includes the necessary front matter fields.
• If your partial isn’t working, try clearing the cache with hugo –ignoreCache.
• Always provide a complete [related] config section—partial overrides do not work, and omitting indices disables them.

Conclusion

With the above steps, you will have a robust related articles section on your Hugo-powered website. The setup is highly configurable. Experiment with weights and content fields to achieve the best relevance for your audience.