creating an interactive knowledge base using jekyll collections and search

By -

Why Build a Knowledge Base with Jekyll

A well-structured knowledge base helps customers and users find solutions quickly without support intervention. Using Jekyll, you can create a high-performance static knowledge base that’s easy to update, scalable, and doesn’t rely on server-side technologies. With collections and search integration, you can deliver an experience that rivals dynamic platforms like Help Scout or Zendesk.

Jekyll Collections: The Foundation of Structured Content

Jekyll collections allow you to define custom content types beyond blog posts and pages. This is ideal for a knowledge base where you may want to organize content by:

  • FAQs
  • Troubleshooting guides
  • Tutorials or how-to articles

Add the following to your _config.yml:

collections:
  kb:
    output: true
    permalink: /kb/:title/

Organizing Your Knowledge Base Content

Create a folder called _kb. Inside, add Markdown files for each knowledge base article:

_kb/
  getting-started.md
  reset-password.md
  contact-support.md

Each file should have front matter for categorization and search indexing:

---
title: Resetting Your Password
category: account
tags: [password,login,troubleshooting]
description: Learn how to reset your password if you've forgotten it.
---

Displaying Articles by Category

In a category page, you can loop through site.kb and filter by category:

{% raw %}
{% assign articles = site.kb | where: "category", "account" %}

{% endraw %}

Client-Side Search Integration

To make your knowledge base searchable, integrate a JavaScript-based search like Lunr.js or FlexSearch. First, generate a JSON index:

Step 1: Create search.json

Add this file in your root directory:

---
layout: null
---
[
  {% raw %}{% for article in site.kb %}{% endraw %}
    {
      "title": {% raw %}"{{ article.title | escape }}",{% endraw %}
      "url": {% raw %}"{{ article.url }}",{% endraw %}
      "content": {% raw %}"{{ article.content | strip_html | strip_newlines | escape }}" {% endraw %}
    }{% raw %}{% if forloop.last == false %},{% endif %}
  {% endfor %}
]

Step 2: Add Search UI

Include a search bar and a results container:

    Step 3: Load Index and Filter

    Use JavaScript to load the JSON and filter results:

    Case Study: Technical Support KB for a SaaS Tool

    A software company built their knowledge base using Jekyll collections and Lunr.js search. Their setup included:

    • 500+ articles across 12 categories
    • Real-time search powered by Lunr.js with auto-complete
    • Separate search.json files for each language

    This allowed them to cut support tickets by 42% in the first 3 months. Updates are made via GitHub, with changes pushed through CI/CD to Netlify in seconds.

    Enhancing UX with Breadcrumbs and Tags

    To improve navigation, implement breadcrumbs using the page’s category and title:

    Knowledge Base > Account > Resetting Your Password

    Also, add tag-based filtering:

    {% raw %}

    Tags:
  {% for tag in page.tags %}
    {{ tag }}
  {% endfor %}

    
{% endraw %}

    Deploying Your Knowledge Base

    Host your knowledge base on:

    • GitHub Pages
    • Netlify with preview builds
    • Cloudflare Pages for fast global delivery

    Maintaining and Scaling the System

    Keep things scalable by:

    • Using a consistent file naming convention
    • Versioning articles via Git history
    • Running a script to check for broken links across articles

    Conclusion

    Building a Jekyll-powered knowledge base provides full control over structure, performance, and UX. With collections, you gain powerful content modeling. Paired with JavaScript search and thoughtful navigation, you create a user-first experience that helps reduce support load and scales indefinitely.