Improve your reader engagement with a related posts block for your site using the flexible theme layer in Ghost.

Overview

Adding a related posts block on each post on your site is a great way to ensure your readers have a positive experience and encourages them to move around your site content once they land on a post.

This is possible using the Handlebars theme layer by creating a partial template and utilising the {{#get}} helper. This tutorial will walk you through building your own related posts block ready for deployment on your Ghost publication ✨

Add a partial reference to default.hbs

The first steps involve creating a new partial template. The /partials directory in a Ghost theme is optional, but it's a useful tool to create blocks of HTML that will be used between multiple templates in your theme. This reduces code duplication and makes the building blocks of your theme easier to work with.

First of all, create a reference to your new partial in the relevant template(s) where you would like the block to appear, for example:

...
{{ghost_head}}
</head>
<body class="{{body_class}}">
  <section class="blog-content">
    {{{body}}}
  </section>

  {{> sidebar}}
  
  {{ghost_foot}}
</body>

For the purposes of this tutorial, we're calling our partial "sidebar" and referencing it with {{> sidebar}} in the defaut.hbs template. You can call your partial anything you like so long as it makes sense to you. In this example, you can imagine that the related posts block is intended to appear in the sidebar of the theme 🙃

This reference will usually be placed in the default.hbs, post.hbs or page.hbs. The great thing about working with partials is that they're reusable, so if you need to use this content block on various templates or parts of your site, then you can!

Create a partial template and add some HTML

Next we need to create a partial template in partials/ and add some HTML to create the skeleton of our related posts block. Here's an example which exists in partials/sidebar.hbs:

<aside class="blog-sidebar">
  <section class="recent-posts">
    <h3>Recent posts</h3>
    <ol>
      <li><a href=""></a></li>
    </ol>
  </section>
  
  <section class="featured-posts">
    <h3>Featured posts</h3>
    <ol>
      <li><a href=""></a></li>
    </ol>
  </section>
</aside>

In a Ghost theme each page belongs to a context, and each context provides some essential data by default. When you need extra dynamic data other than what the context provides, you can fetch it using the {{#get}} helper. This helper makes a custom query to the Ghost API to fetch publicly available data - which is why it's so useful when used as a block helper.

It's possible to fetch a variety of data for your related posts block depending on your requirements. Here's the most popular configurations:

  • Related posts by topic
  • Recently published posts
  • Featured posts

All of these configurations for a related posts block can be achieved using the {{#get}} helper and are documented below:

The most effective way to show posts that are related by topic in your related posts block is to filter by tag. For example:

{{#get "posts" limit="5" filter="tags:[{{post.tags}}]+id:-{{post.id}}" include="tags" as |related|}}
{{/get}}

This provides up to 5 related posts that match the tags of the post the reader is currently on, and excludes the current post from appearing in the featured block. Since these are related posts, block parameter syntax is used to name the data with as |related|.

Recently published posts

The call to the get helper to feature your most recently published posts looks like this: {{#get "posts" limit="3"}}. It's also useful to exclude the current post with a filter here too, and add the block parameter syntax for naming:

{{#get "posts" limit="3" filter="id:-{{post.id}}" as |recents|}}

If you want to call posts that have been checked as featured from the Ghost editor in your block, use a filter parameter:

{{#get "posts" filter="featured:true+id:-{{post.id}}" limit="3" as |featured|}}
Tip 💡 the resource must always come first, and the block parameter to name the data must be last – but parameters like limit and filter can be added in any order.

Use the {{foreach}} helper

Now that you understand how to fetch the relevant data using one of the methods above in your partial template, the final step is to use the {{foreach}} helper to iterate the posts in your related posts block. For example, plugging this into the partials/sidebar.hbs for featured posts will look like this:

{{#get "posts" filter="featured:true" limit="3" as |featured|}}
<section class="featured-posts">
  <h3>Featured posts</h3>
  <ol>
    {{#foreach featured}}
    <li><a href="{{url}}">{{title}}</a></li>
    {{/foreach}}
  </ol>
</section>
{{/get}}

Using {{else}} as a fallback

In the event that no posts match the filter, utilise the {{else}} helper to render alternative content and ensure that your readers aren't staring at an empty space. For example:

{{#get "posts" filter="featured:true" limit="3" as |featured|}}
<section class="featured-posts">
  <h3>Featured posts</h3>
  <ol>
    {{#foreach featured}}
    <li><a href="{{url}}">{{title}}</a></li>
    {{/foreach}}
  </ol>
</section>
{{else}}
<p>Content for a fallback when no related posts are available.</p>
{{/get}}

This is just an example. You could feature pretty much anything here as a fallback... link to a static page on your site, add some text that describes what your publication is all about or insert your favourite meme - you do you!

Implement your new templates

Once you've finished creating your partial template and made any necessary adjustments to your CSS files, update your site's active theme to get it up and running. The easiest way to implement a new theme is to upload the .zip file in Ghost Admin under the Design Settings menu.

Summary

You've completed the tutorial and hopefully deployed a neat featured image block on your Ghost publication. Your new content block is a partial Handlebars template which can be used across any template in your theme when required.

Don't forget you can use the Handlebars documentation anytime to learn more about themes and access a full reference list of available helpers.