jekyll-better-related
jekyll-better-related scores related posts in Jekyll by how many tags, categories, and title keywords they share.
Open Source Plugin ∙

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