How to show related posts in Hugo

Since I started using Hugo, I noticed a lack of plugins or shortcodes for lists of related or featured posts. Coming from the world of digital-marketing / content writers - I know it’s valuable to list: related posts, featured content, content in a series for your readers.

Depending on the theme, you might already have some code that shows your latest posts … and this post shows how you can use this to for related posts. In fact you can get away with writing 1 line of code.

This article shows

1. Check your theme - latest posts
2. Adapt the code for Related posts
3. How to show a different sidebar for list vs single post
4. What to check if it goes wrong

And a worked example using my site so you end up with this

Check your Theme - Latest Post

This is the code in my theme for showing 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" "blog" )}}
	          <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>

Create a Related Post Section

Of course you want to use the same style as your ’latest post’ so - just copy / paste the code that you want.

You then make 2 changes — the name for the section, and the code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

	  <div class="widget mb-5">
	      <h4 class="mb-4 widget-title">Related Posts</h4>
	      <ul class="list-unstyled">
			{{ $related :=  .Site.RegularPages.Related . }}
	        {{ range first 3  $related }}
	        <li class="d-flex mb-4">
	          <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>

The above will work on whatever is the main content section (like blog or post) - because it is using a .mainsections This should be used in themes, as it avoids hard-coding the content type.

Depending on your theme .. you might see these examples of code which also work:

• showing hardcoded content type {{ $related := (where (.Site.RegularPages.Related .) "Type" "blog") }}
• same query but looking in the .mainsections {{ $related := (where (.Site.RegularPages.Related .) "Type" "in" site.Params.mainSections) }}

How to show a different Sidebar for Single Posts?

My theme has one sidebar for the entire site. Related Posts will not work when viewing a top-level / taxonomy page. So lets use the sidebar with related posts only for viewing a single post.

1. Open your Themes Folder - layouts/partials/ and
2. Duplicate the sidebar.html file and call it sidebar-single.html
3. Open your default layout for a post - layouts/default/single.html
4. Look for where the sidebar file gets called {{ partial "blog-sidebar.html" . }} and change it to the file you just duplicated {{ partial "blog-sidebar-single.html" . }}

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.

Test and Go

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

Do check a few other posts to see you are getting the right effect. Then go ahead and deploy it.

If you find a problem

• check the $related have you set this to blog? or post? or another section
• 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

• RegisPhilbert
• Hugo Docs
• .mainsections Discourse

Meet the author

Damien Saunders
An experienced management consultant and business leader interested in digital transformation, product centred design and scaled agile. If I'm not writing about living with UCTD (an autoimmune disease), I'm probably listening to music, reading a book or learning more about wine.
Find our more about me.