
jekyll-better-related
A Jekyll plugin that picks related posts by scoring shared tags, categories, and title keywords instead of just showing your newest posts.
jekyll-better-related replaces Jekyll’s built-in related posts, which just returns your most recently published posts, with an actual relevance score. Each candidate post gets scored against the current one on shared tags, categories, and title keywords, and a small recency penalty breaks ties.
The Problem with Jekyll’s Built-In
Out of the box, site.related_posts is just your N most recent posts. It has no idea what the current post is about. Someone reading about a niche topic gets shown posts on totally different subjects only because they’re recent. That’s useless.
How It Scores
| Signal | Points |
|---|---|
| Shared tag | +3 per tag |
| Shared category | +2 |
| Shared title keyword | +1 per word |
| Age difference | −0.1 per 30 days |
Tags and categories match case-insensitively. Common English stop words don’t count toward title keyword scoring, so you won’t get false matches on words like “the,” “and,” or “your.”
The plugin puts its results in page.related_posts on every post. It doesn’t replace site.related_posts, so nothing breaks if your theme already uses that.
Installation
Add to your Gemfile:
gem "jekyll-better-related"
Add to plugins: in _config.yml:
plugins:
- jekyll-better-related
Configuration
All settings are optional:
better_related:
count: 5 # max related posts to surface (default: 5)
min_score: 1 # minimum relevance score; 0 disables (default: 1)
cross_collection: false # include posts from other collections (default: false)
Template Usage
Use page.related_posts in your post layout:
{% if page.related_posts and page.related_posts.size > 0 %}
<h2>Related Posts</h2>
<ul>
{% for post in page.related_posts %}
<li><a href="{{ post.url }}">{{ post.title }}</a></li>
{% endfor %}
</ul>
{% endif %}
Per-Post Frontmatter Options
Turn it off for a specific post:
related_posts: false
Or list the post URLs yourself to override the scoring:
related_posts:
- /2024/01/some-post/
- /2024/02/another-post/
Source
Available on GitHub and RubyGems.
Install with:
gem install jekyll-better-related

