version-aware search for jekyll documentation sites

Why Version-Aware Search Matters

When your Jekyll site hosts multiple versions of documentation, traditional client-side search can confuse users by mixing results from all versions. This leads to outdated content being surfaced for users who are viewing the latest version—or vice versa.

To provide a better experience, your search should return results scoped to the version the user is currently reading. This helps maintain context and reduces friction.

Step 1: Structure Content for Search Indexing

Ensure each documentation file includes the version in its front matter. Example:

---
title: "Setup Guide"
version: "v2.0"
layout: doc
permalink: /docs/v2.0/setup-guide/
---

This metadata will be used to scope results in the search engine.

Step 2: Generate a Search Index with Version Metadata

Create a JSON index of your docs collection that includes the version, title, url, and an excerpt.

{% raw %}
---
layout: null
---
[
  {% assign docs = site.docs | sort: "title" %}
  {% for doc in docs %}
  {
    "title": "{{ doc.title | escape }}",
    "version": "{{ doc.version }}",
    "url": "{{ doc.url | relative_url }}",
    "content": {{ doc.content | strip_html | jsonify }}
  }{% if forloop.last == false %},{% endif %}
  {% endfor %}
]
{% endraw %}

Save this as search.json in your root folder and reference it from your HTML.

Step 3: Add Lunr or Elasticlunr.js for Search

Include a lightweight search library like Lunr.js or Elasticlunr.js via CDN. For example:

<script src="https://unpkg.com/lunr/lunr.js"></script>

Then fetch the search.json file and load it into the search engine.

Step 4: Filter Results by Current Version

Detect the current version from the URL. For example, if the user is on /docs/v2.0/, use JavaScript to extract v2.0.

const currentVersion = window.location.pathname.match(/\/docs\/(v[\d\.]+)\//)?.[1];

When searching, filter results to match only documents of the same version:

const filteredResults = results.filter(result => result.doc.version === currentVersion);

Step 5: Build the Search UI

Add a simple input field and results container:

<input type="text" id="searchBox" placeholder="Search docs..." />
<ul id="searchResults"></ul>

Then use JavaScript to update the results live as users type:

document.getElementById('searchBox').addEventListener('input', function (e) {
  const query = e.target.value;
  const matches = idx.search(query);
  const scoped = matches.map(m => m.ref).filter(ref => indexMap[ref].version === currentVersion);
  
  // render scoped results
});

Step 6: Link Back to Matching Pages

Each result should include the title and a clickable link that points users to the right version of the page:

<li><a href="/docs/v2.0/setup-guide/">Setup Guide (v2.0)</a></li>

Step 7: Optional Enhancements

• Add fuzzy search or synonyms support.
• Highlight matched keywords in results.
• Allow toggling between all-versions or version-filtered search.

Conclusion

By creating a version-aware search experience for your Jekyll site, you're guiding users more effectively through your content. Whether they’re exploring v1.0 or your latest release, they’ll only see results that are relevant to their context—an important step for improving usability and user satisfaction.

Up next, we’ll discuss how to set up smart redirects and default version handling in your Jekyll knowledge base site.