enhancing ux in searchable jekyll documentation

Why User Experience Matters in Documentation

Even the most complete documentation can feel unusable if the design is confusing. A great user experience makes information easy to find, understand, and navigate — especially in a searchable knowledge base.

This guide is for beginners who already have a basic searchable Jekyll site and want to improve it with UI/UX enhancements like search highlighting, keyboard navigation, sticky headers, and clean layouts.

Better Search Input Positioning

The search box should always be easy to access. A good place is the top of the sidebar or fixed in the header.

<div id="search-container" style="position: sticky; top: 0; background: white; padding: 1rem;">
  <input id="searchInput" type="text" placeholder="Search..." style="width: 100%; padding: 0.5rem;">
</div>

Use CSS to give it shadow, rounded corners, and consistent padding so it feels natural and non-intrusive.

Add Search Result Highlighting

Help users find keywords by highlighting them in results. Here’s a way to add basic highlighting using JavaScript:

function highlightTerms(text, query) {
  const terms = query.split(/\s+/).filter(Boolean);
  terms.forEach(term => {
    const re = new RegExp(`(${term})`, 'gi');
    text = text.replace(re, '<mark>$1</mark>');
  });
  return text;
}

function displayResults(results, pages) {
  const container = document.getElementById('results');
  container.innerHTML = '';

  results.forEach(result => {
    const match = pages.find(p => p.url === result.ref);
    const snippet = highlightTerms(match.content.substring(0, 200), searchInput.value);

    const div = document.createElement('div');
    div.innerHTML = `<a href="${match.url}"><strong>${match.title}</strong></a><br/><p>${snippet}</p>`;
    container.appendChild(div);
  });
}

Keyboard Shortcut for Search

Advanced users expect to press / to focus the search bar, just like in many developer websites. Add this event listener:

document.addEventListener('keydown', function (e) {
  if (e.key === '/' && document.activeElement.tagName !== 'INPUT') {
    e.preventDefault();
    document.getElementById('searchInput').focus();
  }
});

This small feature dramatically improves UX without visual clutter.

Create a Clean and Minimal Layout

Use a sidebar with collapsible sections for navigation. Minimize distractions. Here's a layout idea:

• Left sidebar for navigation
• Main content area for docs
• Sticky header for search and version info

A simple Flexbox layout can achieve this:

<style>
.layout {
  display: flex;
  min-height: 100vh;
}
.sidebar {
  width: 250px;
  background: #f8f9fa;
  padding: 1rem;
  overflow-y: auto;
}
.content {
  flex: 1;
  padding: 2rem;
}
</style>

<div class="layout">
  <aside class="sidebar">
    <!-- Navigation links here -->
  </aside>
  <main class="content">
    <!-- Documentation content -->
  </main>
</div>

Sticky Headers and Context Awareness

To keep context while scrolling, use sticky headings or breadcrumbs:

<div class="breadcrumb" style="position: sticky; top: 0; background: white; z-index: 10;">
  <a href="/docs/">Docs</a> / <a href="/docs/v2.0/">v2.0</a> / <span>Installing</span>
</div>

Dark Mode Toggle

Add a dark mode button using CSS variables:

<style>
:root {
  --bg: white;
  --fg: black;
}
[data-theme="dark"] {
  --bg: #121212;
  --fg: #e0e0e0;
}
body {
  background: var(--bg);
  color: var(--fg);
}
</style>

<button onclick="toggleTheme()">Toggle Dark Mode</button>

<script>
function toggleTheme() {
  const isDark = document.body.getAttribute('data-theme') === 'dark';
  document.body.setAttribute('data-theme', isDark ? 'light' : 'dark');
}
</script>

Responsive Design for Mobile

Many users browse docs from mobile. Make your layout responsive using media queries:

<style>
@media (max-width: 768px) {
  .layout {
    flex-direction: column;
  }
  .sidebar {
    width: 100%;
    order: 2;
  }
  .content {
    order: 1;
  }
}
</style>

Visual Cues for Updated Content

Add badges or markers on recently updated articles to indicate freshness. You can do this manually or automate with YAML front matter like:

---
title: "Installing"
last_updated: 2025-05-10
---

Then in your layout:

<p>Last updated: <time datetime="{{ page.last_updated }}">{{ page.last_updated }}</time></p>

Conclusion

Improving the experience of a searchable Jekyll knowledge base goes beyond just adding search. By focusing on layout clarity, interactive elements, and user expectations like keyboard shortcuts and responsiveness, you create a documentation site that users enjoy returning to.

In the next article, we’ll focus on optimizing build performance and search index sizes for large documentation projects hosted on GitHub Pages.