Jekyll + lunr.js = Static websites with powerful full-text search using JavaScript

Plugin to provide client-side search capability to your Jekyll powered static website.


  JavaScript Jekyll

After discovering lunr.js last week I immediately thought that it would be an ideal way of providing full-text search to Jekyll powered static websites, such as this.

Inspired by two existing Jekyll plugins, Pascal Widdershoven’s Jekyll + indextank and Michael Levin’s Sitemap.xml Generator. I had the foundation for a new plugin, now published on github as jekyll-lunr-js-search.

The new plugin handles the generation of a lunr.js compatible .json index file. In addition, the runtime search configuration is provided by a simple jQuery plugin.

It allows full-text search of all your Jekyll pages and posts. Executed by the client without any server-side processing (outside of serving static files).

Demo

The search plugin is deployed to this site at /search/. Some example search queries are git, cqrs and full-text search.

To minimise JavaScript resource HTTP requests on the homepage I have added on-demand loading of the search plugin .js when focusing into the search field.

Implementation

Publishing

  1. All pages and posts for the site, that are not excluded, are collected together.
  2. Each included item is rendered. The content is extracted using Nokogiri to parse the HTML and take only the paragraph text.
  3. A search.json file is written containing the title, url, published date and extracted, plain body text of every included page and post.

Searching on the client

  1. jQuery plugin first retrieves the search index file using a $.getJSON request.
  2. It populates a lunr.js search index from this data.
  3. URL is parsed for a ?q=term query string parameter. If present, the search input field is populated and a search executed.
  4. keyup event of the search input field is bound to searching, but only executed when least 3 characters have been entered. Search occurs as the user types.
  5. Search result matches found by lunr.js are shown using a Mustache.js template.

How to use

The README on the project’s GitHub page describes the steps to install and configure the Jekyll plugin.