Middleman::Search

LunrJS-based search for Middleman.

Installation

Add this line to your application's Gemfile:

gem 'middleman-search'

And then execute:

$ bundle

Or install it yourself as:

$ gem install middleman-search

Usage

You need to activate the module in your config.rb, telling the extension how to index your resources:

activate :search do
  search.resources = ['blog/', 'index.html', 'contactus/index.html']
  search.index_path = 'search/lunr-index.json' # defaults to `search.json`
  search.fields = {
    title:   {boost: 100, store: true, required: true},
    content: {boost: 50},
    url:     {index: false, store: true}
  }
end

Where resources is a list of the beginning of the URL of the resources to index (tested with String#start_with?), index_path is the relative path of the generated index file in your site, and fields is a hash with one entry for each field to be indexed, with a hash of options associated:

  • boost Specifies lunr relevance boost when searching this field
  • store Whether to store this field in the document map (see below), defaults to false
  • index Whether to index this field, defaults to true
  • required The resource will not be indexed if a field marked as required has an empty or null value

Note that a special field id is included automatically, with an autogenerated identifier to be used as the ref for the document.

All fields values are retrieved from the resource data (ie its frontmatter), or from a data hash inside its options in resource.metadata, except for:

  • url which is the actual resource url
  • content the text extracted from the rendered resource, without including its layout

You should also require the lunr.min.js file to your all.js file:

//= require lunr.min

Index file

The generated index file contains a JSON object with two properties:

  • index contains the serialised lunr.js index, which you can load via lunr.Index.load(lunrData.index)
  • docs is a map from the autogenerated document ids to an object that contains the attributes configured for storage

You will typically load the index into a lunr index instance, and then use the docs map to look up the returned value and present it to the user.

Acknowledgments

A big thank you to: