back to blog

How to HubL : Related Posts for Your Hubspot Blog

5 min read • February 22, 2020

Welcome to the first of a series. In my years working in Hubspot I’ve scoured the HubL documentation aplenty and learned many things through trial and error. Now I am here to share that knowledge with you; snippets and explanations that will hopefully be helpful to both HubL newbies and veterans. Let’s get started!

Related Blog Posts

Related posts are a great source of internal links. Most importantly, they help keep users engaged with your website by showing them more content they may be interested in reading.

Previously, developers would use the blog_recent_posts or blog_recent_tag_posts function to create a related post section, doing so by checking for a tag in the current post and comparing it to the blog's recent posts. Consequently, this required some extra coding to ensure the current post wouldn’t show in the listing. It also wasn’t as robust marketing-wise since it would only show the most recent posts, so older posts would be left to drift away into the aether of the web.

However, Hubspot eventually released the highly customizable related_blog_posts function!


The following can either be coded into a custom module to add into any blog post template or added directly into the post content code.

Create a Macro

We’ll begin by creating a macro of the HTML markup for our related posts section. Usually we would use a macro to easily reuse code snippets, but here we’re using it to allow formatting of the output of the related posts function. We’ll include the list of topic tags, the featured image, post name, author, publish date (using the datetimeformat() function to format the date), and summary. We'll pass a ‘post’ argument into the formatter macro and, secondly, use post.[insert blog variable] to output the post’s information.

You can view a list of available blog variables in Hubspot’s HubL reference documentation.

The macro (formatter) can be named whatever we’d like it to be and likewise for the argument passed into the macro (post).

Add the Related Blog Posts Function

Now that we have our macro we can add our related_blog_posts function. Below is a simple example of the function wrapped in a div to create a section with a header.

blog_ids Here you will add the IDs for the blog(s) you want to pull posts from. The example below shows two IDs therefore posts will be pulled from two different blogs. You can find your blog ID in the URL of the blog dashboard.
limit The number listed here will limit the number of posts that are shown. Here I’ve set the limit to 3 so only three related posts will be printed to the page.
post_formatter This is where you add the name of the macro we’ve created for formatting the output.

As a result the function will output three posts, from two different blogs in our specified HTML markup. The list of posts shown will be chosen based off a relevancy score through a comparison between the current post and other posts in your blog. Moreover, we can further define the type of posts we want shown by adding any of the following parameters:


blog_authors Shows posts from specific authors.
blog_post_ids If we use the related posts function on a regular Hubspot page instead of a blog post we can add IDs of blog posts here to aid the function in finding relevant posts for the page.
start_date / end_date Filters the posts to only ones published within a given time period.


tags If we list any tags here posts labeled with those tags will be given priority.
path_prefixes With this parameter we can give priority to posts listed under specific url paths.
blog_post_override ID's we list in this parameter are added to the listing no matter the other parameter values listed. The posts’ ID can be found in the url of the post’s post editor.

After that all we need is to eye-catchingly style the section to keep users on our website, that is to say, enticing them to read more of our informative blog posts.