jekyll-better-related
A Jekyll plugin that scores related posts by tag overlap, shared categories, and title keyword overlap — not just recency like Jekyll's built-in.
jekyll-better-related replaces Jekyll’s built-in related posts — which just returns the most recently published posts — with a proper relevance algorithm. Every candidate post is scored against the current post on shared tags, categories, and title keywords, with a small recency penalty to break ties.
The Problem with Jekyll’s Built-In
Out of the box, site.related_posts is nothing more than your N most recent posts. It has zero awareness of what the current post is about. Readers browsing a niche topic get shown posts about completely different subjects just 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 are matched case-insensitively. Common English stop words are excluded from title keyword scoring so you don’t get false overlap on words like “the,” “and,” or “your.”
The plugin injects results into page.related_posts for every post — it does not 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
Opt out entirely for a specific post:
related_posts: false
Or supply an explicit list of post URLs to override scoring:
related_posts:
- /2024/01/some-post/
- /2024/02/another-post/
Source
Available on GitHub and RubyGems.
Install with:
gem install jekyll-better-related
jekyll-streetview
jekyll-keepachangelog
