jekyll-better-related

A Jekyll plugin that replaces Jekyll's useless built-in related posts (which just returns the most recent posts) with a proper relevance-scored algorithm.

Why?

Jekyll's site.related_posts is just the N most recently published posts — it has nothing to do with the current post's content. jekyll-better-related scores every candidate post on shared tags, categories, and title keywords, with a small recency penalty, so readers actually get posts that are relevant to what they're reading.

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 keyword scoring.

Installation

Add to your Gemfile:

gem "jekyll-better-related"

Add to plugins: in _config.yml:

plugins:
  - jekyll-better-related

Configuration

All settings are optional. Defaults are shown:

better_related:
  count: 5          # max related posts to surface
  min_score: 1      # minimum relevance score; 0 disables threshold
  cross_collection: false  # include posts from other collections

Template Usage

The plugin injects results into page.related_posts for every post. Use it in your 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 %}

page.related_posts is always an Array (may be empty), so checking .size > 0 before rendering is safe.

Per-Post Frontmatter Options

Opt out entirely

related_posts: false

Manual override

Supply an explicit list of post URLs (relative to site root). The plugin resolves them from the site and skips scoring:

related_posts:
  - /2024/01/some-post/
  - /2024/02/another-post/

GitHub Pages / Safe Mode

This plugin uses a custom Generator and cannot run in GitHub Pages' safe mode. Use a CI/CD build step (GitHub Actions, Cloudflare Pages, etc.) to build and deploy.