Last modified: August 22, 2025
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.

​
Parameters

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.
ParameterTypeDescriptionDefault
limitnumberThe max number of blog posts to list.3
blog_ids’default’ or blog idThe ID(s) of a blogs to include posts from.none
tagsStringThe 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_authorsStringThe names of authors to include posts from (comma separated)none
blog_post_idsStringThe 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_formatterStringThe name of a custom macro to render returned blog posts. The macro is passed three parameters which are the 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.

Note: It is recommended to use the callback parameter below in place of the ‘post_formatter’ parameter as the HTML of the tag will render more quickly, decreasing page load times.		none
callbackStringThe name of a javascript function to render returned blog posts. The function is passed an array of blog post objects to format. If neither the callback, or post_formatter parameters are specified, the tag will generate HTML in a default format.none
path_prefixesStringURL 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_datedate/timeAllows for filtering of posts published after a date/time.none
end_dateDate/TimeAllows for filtering of posts published before a date/time.False
blog_post_overrideStringThe 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
We strongly recommend using the callback parameter instead of the post_formatter parameter to ensure faster page load times.
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 ways to use this tag to enhance your website.

​
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 time frame

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 time frame. 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 using a JS callback to control HTML output

In this example, we generate a listing of 5 posts using the callback parameter to control the HTML output of the post listing. (Instead of the post_formatter parameter using a macro.) 
{% related_blog_posts limit=5, callback="blog_post_formatter" %}

<script>
  var blog_post_formatter = function(blogposts) {

    var formatted = "<div>";
    for (var i = 0; i < blogposts.length; i++) {
      var blogpost = blogposts[i];
      formatted += '<div class="related-blog-item">';
      formatted += `<span>Related Post ${i + 1}/${blogposts.length}</span><br>`;
      formatted += `<a class="related-blog-title" href="https://developers.hubspot.com/docs${blogpost.url}"><span>${blogpost.name}</span></a>`;
      formatted += `<div class="hs-related-blog-byline">by <span class="related-blog-author">${blogpost.blogAuthor.fullName}</span><span class="related-blog-posted-at"> posted on </span><span class="related-blog-date">${new Date(blogpost.publishDate).toLocaleDateString()}</span></div>`;
      formatted += `<p class="related-blog-post-summary">${blogpost.postSummary}<a href="https://developers.hubspot.com/docs${blogpost.url}">Read more</a></p>`;
      formatted += '<div class="related-blog-tags">';
      if (blogpost.tagList.length > 0) {
        formatted += `Tags: ${blogpost.tagList.map(tag => tag.label).join(", ")}`;
      }
      formatted += '</div>';

      if (blogpost.featuredImage) {
        formatted += `<img src="${blogpost.featuredImage}" alt="${blogpost.featuredImageAltText}">`;
      }
      formatted += '</div>';
    }
    formatted += '</div>';
    return formatted;
  }
</script>