Creating a Searchable Knowledge Base in Mediumish

By -

Why Use Jekyll for a Knowledge Base

A knowledge base helps users find answers quickly without reaching out to support. With Jekyll, you can create a lightweight, static, and highly maintainable knowledge base using collections, which separate documentation from blog posts. By integrating client-side search, your content becomes even easier to navigate — and everything works on GitHub Pages.

Core Features You’ll Build

  • Organized knowledge articles via custom collections
  • Semantic structure and hierarchical navigation
  • Client-side search with JSON index
  • Fully static, plugin-free, and hosted on GitHub Pages

Step 1: Define a Collection for Knowledge Articles

Edit your _config.yml to define a new collection:

collections:
  kb:
    output: true
    permalink: /kb/:slug/

This instructs Jekyll to render files inside _kb/ as standalone pages.

Step 2: Create Knowledge Base Articles

Inside the root directory, make a folder named _kb and start adding Markdown files:

_kb/
  setup.md
  install-theme.md
  troubleshooting.md

Each article uses front matter like this:

---
title: "How to Install the Mediumish Theme"
category: "Getting Started"
tags: [theme, installation, mediumish]
summary: "Step-by-step instructions to install the Mediumish theme on Jekyll and GitHub Pages."
---

Step 3: Build a Custom Layout for KB Articles

Create a new layout file: _layouts/kb.html.

{% raw %}
<div class="kb-article">
  <h2>{{ page.title }}</h2>
  <p class="summary">{{ page.summary }}</p>
  <div class="content">{{ content }}</div>
</div>
{% endraw %}

You can also include breadcrumbs, related articles, or tags here.

Step 4: Display Knowledge Base Index Page

Create a page kb/index.html with layout page and a Liquid loop:

{% raw %}
---
layout: page
title: Knowledge Base
permalink: /kb/
---

<h2>Knowledge Base</h2>

{% assign sorted_kb = site.kb | sort: "title" %}
{% for article in sorted_kb %}
  <div class="kb-entry">
    <a href="{{ article.url }}">{{ article.title }}</a>
    <p>{{ article.summary }}</p>
  </div>
{% endfor %}
{% endraw %}

Step 5: Generate a JSON Index for Search

To enable client-side search, create a file named search.json in the root:

{% raw %}
---
layout: null
permalink: /search.json
---

[
  {% for doc in site.kb %}
    {
      "title": {{ doc.title | jsonify }},
      "url": {{ doc.url | jsonify }},
      "summary": {{ doc.summary | jsonify }},
      "content": {{ doc.content | strip_html | strip_newlines | jsonify }}
    }{% if forloop.last == false %},{% endif %}
  {% endfor %}
]
{% endraw %}

Step 6: Add Client-side Search with JavaScript

Create a search input on your kb/index.html page:

<input type="text" id="search" placeholder="Search articles..." />
<div id="results"></div>

And add JavaScript to fetch and filter search.json:

<script>
fetch('/search.json')
  .then(response => response.json())
  .then(data => {
    document.getElementById('search').addEventListener('input', function () {
      const query = this.value.toLowerCase();
      const results = data.filter(doc =>
        doc.title.toLowerCase().includes(query) ||
        doc.content.toLowerCase().includes(query)
      );
      document.getElementById('results').innerHTML = results.map(r => `
        <div class="kb-result">
          <a href="${r.url}">${r.title}</a>
          <p>${r.summary}</p>
        </div>
      `).join('');
    });
  });
</script>

Step 7: Add Category-Based Filtering (Optional)

You can enhance the UI with category filters:

{% raw %}
{% assign categories = site.kb | map: "category" | uniq %}
<select id="filter">
  <option value="">All Categories</option>
  {% for cat in categories %}
    <option value="{{ cat }}">{{ cat }}</option>
  {% endfor %}
</select>
{% endraw %}

Modify the JavaScript to respect selected category when searching.

Benefits of This Setup

  • Fully static: Zero dependencies, works on GitHub Pages
  • Structured: Use of collections for clarity and organization
  • Extensible: Can scale to hundreds of articles
  • Fast: Client-side search avoids loading new pages

Case Study: SaaS Knowledge Base

A small SaaS startup created a knowledge base with ~100 articles using this method. They used GitHub for version control, created category filters for faster discovery, and deployed on GitHub Pages. The result: 40% fewer support tickets and higher organic traffic from Google due to semantic structure and clean URLs.

Next Steps

In the next and final part of this series, we’ll explore how to analyze user behavior within the knowledge base using privacy-friendly tracking and custom Liquid hooks — without external analytics tools.

This will allow you to improve articles based on user searches, clicks, and dwell time — while keeping everything lightweight and self-hosted.