easy related posts for jekyll without javascript

By -

Why Simpler Related Posts Matter

For new Jekyll users, especially those hosting on GitHub Pages, setting up a JavaScript-based related post engine like FlexSearch or Lunr can feel overwhelming. But Jekyll is already powerful enough to create related post sections using just Liquid and front matter. This is ideal for:

  • Small blogs or documentation sites
  • Content with well-defined categories or tags
  • Users who want zero dependencies or JavaScript

Basic Concept of Related Posts in Jekyll

Jekyll processes your Markdown and YAML front matter into a full site at build time. This means you can use logic in your templates to filter, match, and display posts related to the current page by shared metadata like:

  • categories
  • tags
  • layout
  • custom front matter fields

Step-by-Step: Related Posts Without JavaScript

Step 1: Tag Your Posts

Edit your posts and assign tags in the front matter like this:

---
title: "Understanding Liquid Filters"
tags: [liquid,template,jekyll]
categories: [jekyll,guide]
---

Step 2: Add Related Posts Block to Layout

Open your layout file, for example _layouts/post.html, and add the following block at the end:

{% assign current_tags = page.tags %}
{% assign related_posts = site.posts | where_exp: "post", "post != page" %}
{% assign related_posts = related_posts | where_exp: "post", "post.tags | where: 'intersect', current_tags | size > 0" %}

{% if related_posts.size > 0 %}
  <div class="related-posts">
    <h3>You may also like</h3>
    <ul>
    {% for post in related_posts limit:3 %}
      <li><a href="{{ post.url }}">{{ post.title }}</a></li>
    {% endfor %}
    </ul>
  </div>
{% endif %}

Explanation

  • where_exp excludes the current post
  • Filters posts that share at least one tag
  • Limits the result to 3 related posts

Step 3: Style It

You can style your related posts using simple CSS:

.related-posts {
  margin-top: 2rem;
  padding: 1rem;
  border-top: 1px solid #eee;
}
.related-posts ul {
  list-style-type: none;
  padding: 0;
}
.related-posts li {
  margin-bottom: 0.5rem;
}
.related-posts a {
  text-decoration: none;
  color: #007acc;
}

Enhancing the Logic (Optional)

Option 1: Match by Category

If you prefer category-based matching instead of tags, just change post.tags to post.categories in the code.

Option 2: Add Custom Front Matter

Define your own related topics manually for full control:

related_slugs: [how-to-use-liquid, jekyll-config-guide]

Then loop through the site’s posts and compare post.slug:

{% assign related_posts = site.posts | where: "slug", page.related_slugs %}

Benefits of This Method

  • No JavaScript required, ideal for GitHub Pages
  • Works out of the box with Liquid
  • Can be expanded with logic over time
  • Beginner-friendly and maintainable

Limitations to Keep in Mind

  • Only updates when site is rebuilt
  • Relies on good tagging practices
  • Scalability may be limited for large blogs

Conclusion

Building a related post system in Jekyll doesn’t have to involve advanced libraries or heavy client-side scripts. By leveraging Liquid, tags, and a few layout tweaks, you can implement a fast and flexible recommendation system that runs entirely at build time. This keeps your site fast, secure, and perfect for beginners hosting on GitHub Pages.

In the next article, we’ll explore how to combine this logic with pagination and conditional display for a dynamic "Read Next" system.