When you publish multiple articles on GitHub Pages, showing related posts by tags helps visitors continue exploring your content naturally. This method improves both SEO engagement and user retention, especially when you manage a static blog powered by Jekyll. In this guide, you’ll learn how to implement a flexible, automated related-posts section that updates every time you add a new post.
Optimizing User Experience with Related Content
The idea behind related posts is simple: when a reader finishes one article, you offer them another piece that matches their interest. On Jekyll and GitHub Pages, this can be achieved through smart tag connections.
Unlike WordPress, Jekyll doesn’t have a plugin that automatically handles “related posts,” so you’ll need to build it using Liquid template logic. It’s a one-time setup — once done, it works forever.
Why Use Tags Instead of Categories
Tags are more flexible than categories. Categories define the main topic of your post, while tags describe the details. For example:
- Category: SEO
- Tags: on-page, metadata, schema, optimization
When you match posts based on tags, you can surface articles that share deeper connections beyond just broad topics. This keeps your readers within your content ecosystem longer.
Building the Related Posts Logic in Liquid
The following approach uses Jekyll’s built-in Liquid language. You’ll compare the current post’s tags with the tags of all other posts, then display the top related ones.
Step 1 Define the Logic
{% assign related_posts = "" %}
{% for post in site.posts %}
{% if post.url != page.url %}
{% assign same_tags = post.tags | intersection: page.tags %}
{% if same_tags != empty %}
{% assign related_posts = related_posts | append: post.url | append: "," %}
{% endif %}
{% endif %}
{% endfor %}
This code finds other posts that share at least one tag with the current page and stores their URLs in a temporary variable.
Step 2 Display the Results
After identifying the related posts, you can display them as a list at the bottom of your article:
Related Articles
This simple Liquid snippet will automatically list all posts that share similar tags, dynamically updated whenever new posts are published.
Improving the Look and Feel
To make your related section visually appealing, consider using CSS to style it neatly. Here’s a minimal example:
.related-posts {
margin-top: 2rem;
padding: 0;
list-style: none;
}
.related-posts li {
margin-bottom: 0.5rem;
}
.related-posts a {
text-decoration: none;
color: #3366cc;
}
.related-posts a:hover {
text-decoration: underline;
}
Keep the section clean and consistent with your blog design. Avoid cluttering it with too many posts — typically, showing 3 to 5 related articles works best.
Enhancing Relevance with Scoring
If you want a smarter way to prioritize posts, you can assign a “score” based on how many tags they share. The more tags in common, the higher they appear on the list.
{% assign related = site.posts | where_exp: "item", "item.url != page.url" %}
{% assign scored = "" %}
{% for post in related %}
{% assign count = post.tags | intersection: page.tags | size %}
{% if count > 0 %}
{% assign scored = scored | append: post.url | append: ":" | append: count | append: "," %}
{% endif %}
{% endfor %}
Once you calculate scores, you can sort and limit the results using Liquid filters or JavaScript on the client side for even better accuracy.
Integrating with Existing Layouts
Place the related-posts code snippet at the bottom of your post layout file (for example, _layouts/post.html). This way, every post inherits the related section automatically.
{{ content }}
{% include related-posts.html %}
Then create a file _includes/related-posts.html containing the related-post logic. This makes the setup modular, reusable, and easier to maintain.
SEO and Internal Linking Benefits
From an SEO perspective, related posts provide structured internal links. Search engines follow these links, understand topic relationships, and reward your site with better topical authority.
Additionally, readers are more likely to spend longer on your site — increasing dwell time, which is a positive signal for user engagement metrics.
Pro Tip Add JSON-LD Schema
If you want to make your related section even more SEO-friendly, you can add a small JSON-LD script describing related links. This helps Google better understand content relationships.
Testing and Debugging
Sometimes, you might not see any related posts even if your articles have tags. Here are common reasons:
- The current post doesn’t have any tags.
- Other posts don’t share matching tags.
- Liquid syntax errors prevent rendering.
To debug, temporarily output tag data:
{{ page.tags | inspect }}
This displays your tags directly on the page, helping you confirm whether they are being detected correctly.
Final Thoughts
Adding a related posts section powered by tags in your Jekyll blog on GitHub Pages is one of the most effective ways to enhance navigation and keep readers engaged. With Liquid templates, you can build it once and enjoy automated updates forever.
It’s a small addition that creates big results — improving your site’s internal structure, SEO visibility, and overall reader satisfaction.
Next Step
If you’re ready to take it further, you can extend this system by combining both tags and categories for hybrid relevance scoring, or even add thumbnails beside each related link for a more visual experience. Experiment, test, and adjust — your blog will only get stronger over time.