building offline support for jekyll knowledge base

Why Offline-First Matters for Static Documentation

Most developers assume static sites are already lightweight enough, but even static documentation can benefit from offline support. It improves reliability, supports field use (e.g. technical teams without internet), and enhances perceived performance. This is especially useful for knowledge bases or documentation sites built with Jekyll and hosted on GitHub Pages.

Advantages of Offline Support

• Enable content access without internet
• Improve load time on repeated visits
• Reduce dependency on GitHub Pages’ uptime
• Lay the foundation for full Progressive Web App features

What You’ll Need to Set Up

GitHub Pages doesn’t allow server-side code, but with Service Workers and a cache-first strategy, you can create a seamless offline experience using only client-side code and static files.

Basic Requirements

• Valid HTTPS domain (required by Service Workers)
• List of assets to cache (HTML, CSS, JS, JSON)
• A custom service-worker.js file
• Registering the Service Worker on page load

Creating Your Service Worker File

Create a file called service-worker.js at the root of your site:

const cacheName = 'jekyll-knowledge-base-v1';
const staticAssets = [
  '/',
  '/index.html',
  '/search.json',
  '/assets/css/main.css',
  '/assets/js/search.js',
  '/assets/js/autocomplete.js',
  '/favicon.ico'
];

self.addEventListener('install', async event => {
  const cache = await caches.open(cacheName);
  await cache.addAll(staticAssets);
});

self.addEventListener('fetch', event => {
  const req = event.request;
  event.respondWith(cacheFirst(req));
});

async function cacheFirst(req) {
  const cached = await caches.match(req);
  return cached || fetch(req);
}

This service worker pre-caches static files during installation and serves them from cache when offline. You can expand staticAssets to include other collections or pages as needed.

Registering the Service Worker

Add this JavaScript to the bottom of your _layouts/default.html or in a site-wide script:

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker.register('/service-worker.js')
      .then(reg => console.log("Service Worker registered:", reg))
      .catch(err => console.error("Service Worker failed:", err));
  });
}

This will activate your offline mode for any returning user who visits with a modern browser.

Caching Jekyll Collections and Pages

To dynamically generate a list of Jekyll pages or collections to cache, you can create a Liquid-generated asset manifest:

---
layout: null
permalink: /asset-manifest.json
---

[
  {% for page in site.pages %}
    {% unless page.layout == null %}
      "{{ page.url | relative_url }}"{% unless forloop.last %},{% endunless %}
    {% endunless %}
  {% endfor %}
]

Then modify your service worker to fetch and cache these entries during install.

Enabling Offline Search

Since your search logic is client-side and relies on search.json, caching that file enables offline search to work as well. Ensure you add it to your asset list.

Test Offline Search Scenario

1. Load your site while online
2. Visit 2–3 article pages
3. Disconnect from the internet
4. Try navigating to previously visited pages and using the search box

If implemented correctly, content loads from cache, and search functionality continues to work without an active connection.

Expanding to Full PWA Capabilities

To truly turn your knowledge base into a Progressive Web App (PWA), consider adding:

• manifest.json file with app name, icon, theme color
• Home screen install prompt support
• Background sync or push notifications (if using external APIs)

Sample manifest.json

{
  "name": "Jekyll Knowledge Base",
  "short_name": "KnowledgeBase",
  "start_url": "/",
  "display": "standalone",
  "theme_color": "#ffffff",
  "background_color": "#ffffff",
  "icons": [{
    "src": "/icon.png",
    "sizes": "192x192",
    "type": "image/png"
  }]
}

Then reference it in your layout's head:

<link rel="manifest" href="/manifest.json">

Best Practices for Static Offline Support

• Version your cache names to bust outdated files
• Don’t cache admin-only or private pages
• Use lazy caching if the site grows large
• Monitor Service Worker errors in browser console

Conclusion

Offline-first experiences are not just for mobile apps. Even your static Jekyll documentation can benefit from them. By setting up a simple Service Worker, you can dramatically increase your site’s usability, even in low-connectivity scenarios.

Combined with searchable JSON indexes and client-side logic, your knowledge base becomes more robust, reliable, and modern—all without leaving the GitHub Pages ecosystem.