jekyll-better-related 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d33886e0039dce0880cdfe899eba88e942d7e6c757ff001bf5f80a3541f1dca2
+  data.tar.gz: 9fcb3ab8f7fbaa9392e37475538ce8420bf9449751144e4b9c863db1d59d4a36
+SHA512:
+  metadata.gz: 8da0057c3d2569f6ed75b0e5702dee8439385b331244114e4aa8802fee0af0edd275123b8c07ba202722158dacf9233022bd6b6f07b70093719daf04f01e8217
+  data.tar.gz: 8978d32da133a5dcf9ba1f828ab4447c56f2127e47db817b25954ee76ba16d20c68794f34ab5ea7f73d311b732c747c1ddf49fb6d7be3481085a2c31c45268e4

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-08-20
+
+### Added
+- Initial release
+- Relevance scorer using tag overlap (3pts), category match (2pts), title keyword overlap (1pt), recency penalty (−0.1/month)
+- Injects top N results into `page.related_posts` for every post
+- Configurable `count`, `min_score`, and `cross_collection` options
+- Per-post opt-out via `related_posts: false` frontmatter
+- Per-post manual override via `related_posts: [url, ...]` frontmatter
+- 19 tests passing

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jason Chance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,89 @@
+# 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.
+
+[![Gem Version](https://badge.fury.io/rb/jekyll-better-related.svg)](https://rubygems.org/gems/jekyll-better-related)
+
+## 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`:
+
+```ruby
+gem "jekyll-better-related"
+```
+
+Add to `plugins:` in `_config.yml`:
+
+```yaml
+plugins:
+  - jekyll-better-related
+```
+
+## Configuration
+
+All settings are optional. Defaults are shown:
+
+```yaml
+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:
+
+```liquid
+{% 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
+
+```yaml
+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:
+
+```yaml
+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.
+
+## License
+
+[MIT](LICENSE.txt) © Jason Chance

data/lib/jekyll/better_related_generator.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "jekyll"
+
+module Jekyll
+  class BetterRelatedGenerator < Generator
+    safe true
+    priority :low
+
+    # Scoring weights
+    TAG_WEIGHT      = 3
+    CATEGORY_WEIGHT = 2
+    KEYWORD_WEIGHT  = 1
+    # Recency: subtract this many points per 30-day interval of separation
+    RECENCY_PENALTY = 0.1
+    SECONDS_PER_MONTH = 60 * 60 * 24 * 30
+
+    # Common English stop words to exclude from keyword matching
+    STOP_WORDS = %w[
+      a an the and or but in on at to for of with is are was were be been
+      this that it its by from as into about up out if so do does did
+      how what when where who which will would could should have has had
+      not no can more some than then their they them there these those
+      all any each just like may my our own said such use your
+    ].to_set.freeze
+
+    def generate(site)
+      @site   = site
+      @config = site.config["better_related"] || {}
+
+      count      = (@config["count"] || 3).to_i
+      min_score  = (@config["min_score"] || 1).to_f
+
+      candidates = collect_candidates
+
+      site.posts.docs.each do |post|
+        # Per-post manual override: list of URLs
+        override = post.data["related_posts"]
+        if override.is_a?(Array)
+          post.data["related_posts"] = resolve_manual(override)
+          next
+        end
+
+        # Per-post opt-out
+        next if override == false
+
+        scored = candidates
+          .reject { |c| c.equal?(post) }
+          .map    { |c| [c, score(post, c)] }
+          .select { |_, s| s >= min_score }
+          .sort_by { |_, s| -s }
+          .first(count)
+          .map(&:first)
+
+        post.data["related_posts"] = scored
+      end
+    end
+
+    private
+
+    def collect_candidates
+      docs = @site.posts.docs.dup
+      if @config["cross_collection"]
+        @site.collections.each_value do |col|
+          next if col.label == "posts"
+          docs += col.docs
+        end
+      end
+      docs
+    end
+
+    def score(post, candidate)
+      s = 0.0
+
+      # Tag overlap
+      post_tags = Array(post.data["tags"]).map(&:downcase)
+      cand_tags = Array(candidate.data["tags"]).map(&:downcase)
+      s += (post_tags & cand_tags).size * TAG_WEIGHT
+
+      # Category match
+      post_cats = Array(post.data["categories"]).map(&:downcase)
+      cand_cats = Array(candidate.data["categories"]).map(&:downcase)
+      s += (post_cats & cand_cats).size * CATEGORY_WEIGHT
+
+      # Category singular field
+      if post.data["category"] && candidate.data["category"]
+        s += CATEGORY_WEIGHT if post.data["category"].downcase == candidate.data["category"].downcase
+      end
+
+      # Title keyword overlap
+      post_kw = keywords(post.data["title"].to_s)
+      cand_kw = keywords(candidate.data["title"].to_s)
+      s += (post_kw & cand_kw).size * KEYWORD_WEIGHT
+
+      # Recency penalty
+      post_date = post.data["date"]
+      cand_date = candidate.data["date"]
+      if post_date && cand_date
+        months_apart = (post_date.to_time - cand_date.to_time).abs / SECONDS_PER_MONTH
+        s -= months_apart * RECENCY_PENALTY
+      end
+
+      s
+    end
+
+    def keywords(title)
+      title.downcase
+           .gsub(/[^a-z0-9\s]/, " ")
+           .split
+           .reject { |w| STOP_WORDS.include?(w) || w.length < 3 }
+           .to_set
+    end
+
+    def resolve_manual(urls)
+      urls.filter_map do |url|
+        @site.posts.docs.find { |p| p.url == url }
+      end
+    end
+  end
+end

data/lib/jekyll-better-related/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module JekyllBetterRelated
+  VERSION = "0.1.0"
+end

data/lib/jekyll-better-related.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "jekyll-better-related/version"
+require "jekyll/better_related_generator"

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-better-related
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jason Chance
+bindir: bin
+cert_chain: []
+date: 2026-08-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: jekyll-better-related replaces Jekyll's built-in related_posts (which
+  is just recency) with a proper relevance scorer using tag overlap, category match,
+  and title keyword overlap. Drop-in replacement — no theme changes required.
+email:
+- jason@jasonchance.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/jekyll-better-related.rb
+- lib/jekyll-better-related/version.rb
+- lib/jekyll/better_related_generator.rb
+homepage: https://github.com/jchance/jekyll-better-related
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jchance/jekyll-better-related
+  source_code_uri: https://github.com/jchance/jekyll-better-related
+  changelog_uri: https://github.com/jchance/jekyll-better-related/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Relevance-scored related posts for Jekyll — because the built-in is useless.
+test_files: []