Hugo Content Management Series

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

Hugo Related Posts

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