Hugo Content Management Series

Since I started using Hugo, I noticed a lack of plugins or shortcodes for lists of related or featured posts. For bloggers and digital-marketing / content writers , it’s valuable to list: related posts, featured content or content in a series.

This post will focus on Featured Posts and showing these on your homepage or list, any other page.

I’ll show you two approaches to show featured content -

  1. Using a tag or category called ‘featured’, or
  2. Add extra Params / Front Matter call featured

There is also -

  • a real-life worked example
  • Things to check if it goes wrong

Featured Post - as a Tag or Category

Here we use Hugo Taxonomies to show posts with a specific tag. We’re going to extend and use the range function along with .Site.Taxonomies.tags..

So - open the partial / list file where you want to put the featured posts and use this code:

1
2
3
4
5
6
7
	<h3>Featured Posts</h3>
	<ul>
	  {{ range first 3 .Site.Taxonomies.tags.featured }}
		  <li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a>
		  </li>
	  {{ end }}
	</ul>

Notes:

  • if you want to use featured as a category then you can change this {{ range first 3 .Site.Taxonomies.categories.featured }}
  • if you want to show more or less than 3 posts change first 3. This also gets the more recent (as in first) posts.

Featured Post FrontMatter

In this approach, when writing blog / post markdown content you add a parameter in the front matter.

At the top of your markdown files, just add in featured: true so the Front Matter will look like this:

1
2
3
4
5
6
7
8
9
---
title: "My post title"
date: 2020-06-01
tags: 
- hugo
author: Your Name
draft: false
featured: true
---

With some code, you can access this front matter using .Params

Theme Changes for .Params.featured

So - open the theme partial / list file where you want to put the featured posts and use this code:

1
2
3
4
5
6
7
	<h3>Featured Posts</h3>
	<ul>
		{{ range first 3 (where (where .Site.RegularPages "Type" "in" site.Params.mainSections) ".Params.featured" "=" true) }}`
		  <li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a>
		  </li>
	  {{ end }}
	</ul>

This works on pretty much anywhere - if you have blogs, posts or other content types … the query will look at .mainSections. You should use this approach if you’re thinking of internationalisation i18n

The more older and specific to the content type … would be

{{ range first 3 ( where (where .Site.Pages "Type" "blog”) ".Params.featured" "=" true )}}

The end result – using .Params.featured looks like this:

Hugo Featured Posts

Worked Example: if you already have a Latest Post Section

I already have a section showing my Latest Posts — you can see it on my blog

I’ve highlighted the important code which we will change …

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
	      <div class="widget mb-5">
	        <h4 class="mb-4 widget-title">Latest Posts</h4>
	        <ul class="list-unstyled">
	          {{ range first 3 ( where .Site.Pages "Type" "in" site.Params.mainSections )}}
	          <li class="d-flex mb-4">
	            <a href="{{ .Permalink }}" class="mr-3">
	              {{ with .Params.image }}<img src=""....>{{ end }}
	            </a>
	            <div class="post-body">
	              <span class="text-capitalize">- {{ dateFormat "Monday, Jan 2, 2006" .Date }}</span>
	              <a href="{{ .Permalink }}">
	                <h5>{{ .Title }}</h5>
	              </a>
	            </div>
	          </li>{{ end }}
	        </ul>
		  </div>

So to show featured posts (by tag) we change the highlighted line to: {{ range first 3 .Site.Taxonomies.tags.featured }}

Test Driven Development

If you are thinking of Automated Testing with Selenium or other tools … be sure to wrap any custom code with class elements that make them easy to identify for testing.

So now …

  1. Save the file
  2. Commit your changes to Git
  3. Run Hugo server -D and browse to http://Localhost to check every thing is work fine

If you find a problem

  • Check your section and content type - should it be blog? posts? or something else
  • Check the range - have you got enough ( ) in the right places?
  • Check the param is correctly saved in the markdown files
  • Sort order doesn’t appear right? the default sort order can be case-sensitive, so check for consistency in your tags / categories.

Did you find this helpful? Please let me know

Linkage