Jekyll Offline Template is a bare-bones Jekyll boilerplate that adds a service worker to a static site, letting it serve from cache when the network is gone. It is a GitHub template meant for simple, infrequently updated pages hosted on GitHub Pages with HTTPS.
What is Jekyll Offline Template?
Jekyll Offline Template is a minimal Jekyll template whose core function is to make a static website work offline. It takes a Jekyll site (content written in index.md or other Markdown files) and produces a static HTML site that caches itself via a service worker on first visit. The project is hosted on GitHub and follows the standard Jekyll workflow, so you edit Markdown and push to deploy. The service worker is only active when the site is served over HTTPS or from localhost.
Key Features
- Service worker caching — A service worker registers on the site and caches all resources, making the page available without a network connection after the first load.
- Cache exclusivity — When the service worker activates, it purges any caches it can access that do not match its version, preventing stale mixed caches.
- Bare-bones structure — No styling, plugins, or extra dependencies; the template is intentionally minimal and works with plain Jekyll.
- GitHub Pages ready — Deployment requires only creating a repository from the template, enabling GitHub Pages, and turning on HTTPS.
- Manual update flow — Updates are not automatic; the new worker serves only after a refresh and after old tabs are closed, giving you control over when content changes.
Who is it for?
- Developers and technical writers — Create a cheatsheet or reference page that can be accessed offline in environments without internet, such as on a plane or in a remote location.
- Maintainers of infrequently updated sites — Publish a small static page (like a personal tool or a simple manual) that changes rarely, where delayed updates are acceptable.
- Learners exploring service workers — Use this repository as a minimal, readable example of how to add offline capabilities to a static site with Jekyll.
What can you do with it?
- Offline cheatsheets: Write a quick reference in index.md and have it available even when you lose connectivity.
- Self-contained resource pages: Host a page on its own domain so it owns all its resources exclusively, as the README recommends, avoiding interference with other sites' caches.
- Experiments with caching: Test how a service worker behaves with a versioned cache and how browsers handle updates, all in a simple Jekyll environment.
How does it work?
- Create a new repository from the template on GitHub.
- Enable GitHub Pages in the repository settings, and ensure HTTPS is on (required for the service worker to run).
- Edit index.md or add other Markdown files to fill in your content.
- Push to the repository; GitHub Pages builds the Jekyll site and serves it. The service worker then caches the site on the user's first visit.
FAQ
Why does HTTPS matter for offline capabilities?
Service workers are only permitted in secure contexts. If the site is served over plain HTTP (except on localhost), the service worker will not register and offline caching will not work. That is why the quick start steps require enabling HTTPS on GitHub Pages.
How do I update the cached content?
Refreshing the page installs the new service worker version, but the old worker may keep serving until all tabs using it are closed. The README suggests closing all old tabs and reopening the site to see changes. You can also use an incognito session or forcibly unregister the worker via DevTools.
What is the "dumb caching" warning about?
The service worker purges any cached items that don't match its version, and it may affect other caches in the same scope. If you use the same cache names elsewhere, this template's worker could interfere with them. The author intentionally calls it "dumb" because it is primitive but functional.
Can I use this template for frequently changing content?
It is not ideal. The update process requires manual steps—refresh, close tabs, reopen—and the caching is designed for pages that change infrequently. If your content updates often, you would need a more sophisticated service worker strategy.
How do I bypass the service worker for testing?
In Chrome DevTools, the Application tab has a "Bypass for network" checkbox that lets the browser skip the service worker and fetch directly from the server. This is useful for verifying the current version of your page during development.
