Table of contents

Creating a related blog post listing with the blog related posts HubL tag

The related_blog_posts HubL tag can be used to create dynamic and related blog post listing based on a variety of parameters. It allows for generating listings of posts across blogs, with the ability to filter by tags, authors, post paths and publish dates. Developers can also specify the html output of the module using a macro. This HubL tag can be used on both blog posts and pages. This tutorial will walk through the parameters and usage options for the blog related posts HubL tag.

Please note that the related_blog_posts HubL tag does not generate an editable module on the post/page level, it is configured in its entirety with HubL.


The list of posts is generated from a relevancy score based on a comparison of the set parameter values against posts matching these parameters, or relating to the post the HubL tag appears on. None of the parameters are required, however, specifying parameters will allow you to further control which posts are returned. For comma separated parameters, the more values you set, the more diverse the returned listing will be. The post_formatter parameter allows you to specify a macro to generate the HTML output of the module. For a full list of parameters and example default HTML output, please see the related_blog_posts spec.

Parameter name Type Description Default value
 limit  number  The max number of blog posts to list.  3
 blog_ids  'default' or blog ID(s)  The ID(s) of a blogs to include posts from.  none
 tags  string   The tag(s) that should be used to determine if a post is relevant (comma separated). If a blog post has one of these tags or a similar tag, the post’s relevancy is increased, improving its ranking in the listing.  none 
 blog_authors  string  The names of a authors to include posts from (comma separated)  none 
 blog_post_ids  string  The ID(s) of a blog posts to use when finding relevant blog posts to list (comma separated). This parameter should only be used when the widget is appearing on pages, as on blog posts, it will default to the post the widget is appearing on.  none
 post_formatter  string  The name of a custom macro to render returned blog posts. The macro is passed three parameters which are the blog blog post object to format, the count in the iteration of blog posts, and the total count of blog posts in the results. If not specified or set to “default”, the built-in formatter will be used to format each post.  none
 path_prefixes  string  URL paths or subdirectories to include posts from (comma separated). If a blog post has a similar prefix in its path, the post’s relevancy is increased, improving its ranking in the listing.  none
 start_date & end_date  date/time  Allows for filtering of posts published within a time period.  none
 blog_post_override  string  The ID(s) of a blog posts which should always show up in the returned listing, despite all other parameter values and filters (comma separated).  none

Please note that if the related_blog_posts HubL tag is being used on a post, the blog_post_ids parameter should not be specified, as on blog posts, it will default to the post the widget is appearing on.

Below are some example usages of the related_blog_posts HubL tag:

Display posts from a specific author across multiple blogs

In this example, we generate a listing of posts written by one of the three specified blog_authors across two different blogs. 

{% related_blog_posts blog_ids="3241539189,3261083894", limit=6, blog_authors="John Smith,Joe Smith,Frank Smith" %} 

Display posts with the tag “sales enablement”, restricted to a specific publish date timeframe

In this example, we generate a listing of 10 posts related to a specific blog post, with the tag "sales enablement", and restricted to a specific publish date timeframe. This example specifies the blog_post_ids parameter, so it would be used on a page.  

{% related_blog_posts blog_post_ids="3267910554", limit=10, tags="sales enablement", start_date="2018-02-05", end_date="2018-06-10" %}

Display posts with a common path using a macro to control HTML output

In this example, we generate a listing of 5 posts sharing common paths using the path_prefixes parameter. We also specify the post_formatter parameter to control the HTML output of the post listing using a macro

{% macro blog_post_formatter(blog_post, index, count) %}
<div class="related-blog-item">
  <span>Related Post {{ index }}/{{ count }}</span><br>
  <a class="related-blog-title" href="{{blog_post.url}}">
      {{ blog_post.name }}
  <div class="hs-related-blog-byline">
    <span class="related-blog-author">{{ blog_post.blogAuthor }}</span>
    <span class="related-blog-posted-at"> posted on </span>
    <span class="related-blog-date">{{ blog_post.publishDate|datetimeformat('%B %e, %Y') }}</span>
  <p class="related-blog-post-summary">
    {{ blog_post.post_summary }}
    <a href="{{ blog_post.url }}">Read more</a>
  <div class="related-blog-tags">
    {% if blog_post.tagList|length > 0 %}Tags: {% endif %}{{ blog_post.tagList|join(", ") }}
  {% if blog_post.featured_image %}
    <img src="{{ blog_post.featured_image }}" alt="{{ blog_post.featured_image_alt_text|escape }}">
  {% endif %}
{% endmacro %}

{% related_blog_posts limit=5, path_prefixes="/marketing,/sales" post_formatter="blog_post_formatter" %}