Jekyll plugin to identify and link to related posts.
There are other related posts plugins for Jekyll,123 but this one is mine. 😁
Prior to building your site, jekyll-related attaches a bit of metadata to each
posts that ranks all the other posts from most to least related. You can use
this metadata to recommend related posts to your readers, either by using the
included {% related %} tag to automatically insert a list, or by creating a
customized template using the page.related metadata the plugin defines.
Relatedness is computed by counting similar word frequencies, with extra weight given to words that are rare (like "submodular") and less to words that are frequent (like "then").
The dogfood/ directory contains a demo Jekyll site which uses the plugin to rank the similarity of each of the articles in the UN Universal Declaration of Human Rights. You can view the demo site on GitHub pages here.
This gem is not hosted on RubyGems.org. I may upload it eventually; for now, you can depend directly on the git repo by adding the following to your Gemfile:
group :jekyll_plugins do
# Track the main branch. Might break occasionally :D
gem "jekyll-related", git: "https://github.com/maxkapur/jekyll-related", branch: "main"
# Pin a specific git commit
gem "jekyll-related", git: "https://github.com/maxkapur/jekyll-related", ref: "67da865bd33324d4330ca57e419e7782c1e8bc6d"
end
Below is boilerplate generated by the bundle gem command:
TODO: Replace
UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG with your
gem name right after releasing it to RubyGems.org. Please do not do it earlier
due to security reasons. Alternatively, replace this section with instructions
to install your gem from git if you don't plan to release to RubyGems.org.
Install the gem and add to the application's Gemfile by executing:
bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORGIf bundler is not being used to manage dependencies, install the gem by executing:
gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORGThere are a few ways to use this plugin:
- Modify your post layout like this example in the demo
site to use the
{% related %}tag. This inserts an<ol class="related-post-list">with the related post titles, links, and dates as list elements. As an easter egg, the links show the similarity score in the hover text. - Create your own template if you want to tweak the list appearance more
precisely. The Liquid template used by the
{% related %}tag should get you started.
You may configure the following options in your site's _config.yml; the values
below are the defaults:
related:
# Number of related posts to show if using the {% related %} tag (the plugin
# itself always ranks all posts in the metadata). nil means rank all of them.
count: nil
# Relative weight between the most and least frequent words in the corpus.
# A value close to 1 means all words have similar weight; a high value means
# rare words matter a lot. Decrease this value if your recommendations feel
# too random; increase this value if you are getting nearly the same
# recommendations for every post.
factor: 10.0After checking out the repo, run bin/setup to install dependencies. You can
also run bin/console for an interactive prompt that will allow you to
experiment.
To install this gem onto your local machine, run bundle exec rake install. To
release a new version, update the version number in version.rb, and then run
bundle exec rake release, which will create a git tag for the version, push
git commits and the created tag, and push the .gem file to
rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/maxkapur/jekyll-related.
The gem is available as open source under the terms of the MIT License.