improvement(library): rank related posts by tag rarity, add backlinks, and widen comparison and pagination links

Merged
WA
6d ago
+507-91

Summary

  • Related posts ranked by raw tag overlap with a newest-first tiebreak. Sim is on every library post and AI Agents on 120/123, so the list was effectively "the newest posts": 41/123 posts never appeared as related and one post held 46 of the 369 slots
  • New lib/content/links.ts builds a link index once per registry scan: related posts score shared tags and title terms weighted by rarity (a term on more than half the posts weighs zero), plus direct body links between posts, discounted for widely linked hubs. Equal scores break by a per-pair hash, then slug, so the result is deterministic and does not favor one post
  • Library posts show 6 related posts in a responsive grid (1/2/3 columns) instead of a 3-card row
  • The scan also records each post's internal body links, and the reverse index powers a server-rendered "Referenced in" list (up to 6, newest first) on each library post. Related posts skip anything already in that list
  • Comparison ↔ library links: cap raised from 3 to 6. A "{Competitor} Alternatives" title now ranks first, so /comparisons/zapier and /comparisons/n8n lead with their alternatives articles (before, neither listed them). Posts whose body links to /comparisons/<id> now count as matches too. Matching the competitor name in body text was rejected because n8n appears in 113/123 bodies
  • /library and /blog pagination shows numbered page links between Previous and Next. Page 1 links to the bare index instead of ?page=1

Link distribution across 123 published library posts (related-post blocks only, before → after):

Before (3 related)After (6 related + Referenced in)
Posts never linked from another post's blocks410
Most slots held by one post4625 (15 from related alone)
Posts with a "Referenced in" listn/a93
best-zapier-alternatives / n8n-alternatives / langgraph-alternatives related slots0 / 0 / 04 / 8 / 9

For reference, the old algorithm at 6 slots would leave 25 posts never related and give one post 74 slots.

Follow-ups, not in this PR: indexable tag or hub pages, a curated guides block on the homepage, and a site-wide link index so blog posts count as referrers.

Type of Change

  • Improvement

Testing

  • lib/content/links.test.ts (new): link extraction, rarity ranking, and inbound index. The ranking test fails with raw tag-count weights; the inbound test fails without the date sort or the self-link skip
  • app/(landing)/content-routing.test.tsx, lib/content/registry-factory.test.ts pass
  • bun run lint, check:comment-hygiene, check:unused-exports, check:source-conventions, check:file-names, check:boundaries, check:client-boundary, check:utils, check:library-content, check:test-patterns
  • Distribution stats from a read-only script run against the real registry over the current content
  • Type-check, check:audits, and the full test suite run in CI

Checklist

  • Code follows project style guidelines
  • Self-reviewed my changes
  • Tests added/updated and passing (new tests pass the test-audit authoring gate)
  • No new warnings introduced
  • I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)