jekyll_pages_api_search: A Ruby repository from jbarnicle

jekyll_pages_api_search Plugin

This Ruby gem adds a lunr.js search index to a Jekyll-based web site.

The search index is generated and compressed automatically via jekyll build or jekyll serve. The supporting JavaScript code is optimized, compressed, and loads asynchronously. These features ensure that the preparation of the search index does not introduce rendering latency in the browser.

Example of querying the search index and selecting from the search results page. The `/` key moves focus to the search query box, and the first result receives the tab index, making mouse-based navigation unnecessary.

How it works

On the server building the site, the plugin takes the corpus produced by the jekyll_pages_api gem and feeds it to a Node.js script that compiles it into a lunr.js index, serialized as JSON. The plugin adds this output file to the Jekyll site output. It generates a compressed copy as well, enabling web servers to take advantage of sending the compressed output directly, e.g. using the Nginx gzip_static on directive.

The gem also generates a (configurable, customizable) search results page that will serve the search results.

On the client, the search interface box submits a query form that fetches the search results page. The code on the search results page then fetches the search index from the server (which will be cached by the browser until the next site build). After loading the index, the page issues the query and inserts the results into its search results interface element.

All of the client-side components are bundled together with assets/js/search.js into assets/js/search-bundle.js using Browserify.

Installation

Install Node.js on your system. This plugin requires version 4.2 or greater or version 5 or greater. You may wish to first install a version manager such as nvm to manage and install different Node.js versions.
Add this line to your Jekyll project's Gemfile:

group :jekyll_plugins do
  gem 'jekyll_pages_api_search'
end

Add the following to the project's _config.yml file:

# Configuration for jekyll_pages_api_search plugin gem.
jekyll_pages_api_search:
  # Uncomment this to speed up site generation while developing.
  #skip_index: true

  # Each member of `index_fields` should correspond to a field generated by
  # the jekyll_pages_api. It can hold an optional `boost` member as a signal
  # to Lunr.js to weight the field more highly (default is 1).
  index_fields:
    title:
      boost: 10
    tags:
      boost: 10
    url:
      boost: 5
    body:

Run jekyll build or jekyll serve to produce search-index.json and search-index.json.gz files in the _site directory (or other output directory, as configured).
If you're running Nginx, you may want to use the gzip_static on directive to take advantage of the gzipped versions of the search index and supporting JavaScript.

Usage

To add the index to your pages, insert the following tags in your _layouts and _includes files as you see fit:

{% jekyll_pages_api_search_interface %}: inserts the HTML for the search box and search results
{% jekyll_pages_api_search_load %}: inserts the <script> tags to load the search code asynchronously; the search code will then load search-index.json asynchronously

You can also add @import "jekyll_pages_api_search"; to one of your Sass assets to use the default interface style.

Add skip_index: true to the front matter of any documents you would like to exclude from the index (e.g. indexes that contain summaries of other documents).

Configuration

In addition to the fields listed above in the installation instructions, the following properties of the jekyll_pages_api_search configuration object are also available:

results_page_title: Sets the title of the generated search results page.
layout: The name of the layout file for the search results page, minus the .html suffix. By default this is search-results, and is provided by the plugin. If you add a search-results.html to your site's layout_dir (typically _layouts), the plugin will use that layout instead.
endpoint: The name of the endpoint generated for the search results page. Defaults to search.

Customization

If you prefer to craft your own versions of these tags and styles, you can capture the output of these tags and the Sass @import statement, then create new tags or included files based on this output, careful not to change anything that causes the interaction between these components to fail.

Alternately, you can inspect the code of this gem (all paths relative to lib/jekyll_pages_api_search/):

{% jekyll_pages_api_search_interface %}: includes search.html
{% jekyll_pages_api_search_load %}: generated by the LoadSearchTag class from tags.rb
{% jekyll_pages_api_search_results %}: generated by the SearchResultsTag class from tags.rb
@import "jekyll_pages_api_search";: includes sass/jekyll_pages_api_search.scss

Running standalone

If you wish to generate a search-index.json file (and optionaly a pages.json file) when using a site generation tool other than Jekyll, you can run the jekyll_pages_api_search executable as a post-generation step. Run jekyll_pages_api -h for instructions.

Developing

Install Node.js per the installation instructions (step #1). The Rakefile will prompt you to install Node.js and any packages that are missing from your system when running bundle exec rake build.

After cloning this repository, do the following to ensure your installation is in a good state:

$ cd jekyll_pages_api_search
$ npm install
$ bundle install
$ bundle exec rake test

Run bundle exec rake -T to get a list of build commands and descriptions.

Commit an update to bump the version number of lib/jekyll_pages_api_search/version.rb before running bundle exec rake release.

While developing this gem, add this to the Gemfile of any project using the gem to try out your changes (presuming the project's working directory is a sibling of the gem's working directory):

group :jekyll_plugins do
  gem 'jekyll_pages_api_search', :path => '../jekyll_pages_api_search'
end

Contributing

If you'd like to contribute to this repository, please follow our CONTRIBUTING guidelines.

Public domain

This project is in the worldwide public domain. As stated in CONTRIBUTING:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.

jbarnicle/jekyll_pages_api_search