Adds support for client-side search with Lunr, full-text and faceted.
JavaScript CoffeeScript
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
out
src
.gitignore
LICENSE
README.md
package.json

README.md

DocPad Lunr Plugin

Generates Lunr search indexes from your Docpad collections, and provides helpers for a client-side full-text and faceted search.

Getting Started

npm install --save docpad-plugin-lunr

or

docpad install lunr

Configure a collection to index in your docpad.coffee:

plugins:
  lunr:
    indexes:
      myIndex:
        collection: 'myCollection'

To create an index which includes multiple collections you can pass an array of collection names:

plugins:
  lunr:
    indexes:
      myIndex:
        collection: ['firstCollection','secondCollection']

Make your search page itself, eg my-search-page.html.eco:

<%- @getLunrSearchPage('myIndex') %>

Make a "search bar" on other pages that redirects users to your search page above, like in a layout, eg. default.html.eco:

<%- @getLunrSearchBlock('my-search-page.html') %>

Customization

To control the fields that get indexed and their "boost" levels (ie, relevance), add to the index's configuration in docpad.coffee:

indexFields: [
  {name: "body", boost: 1}
  {name: "title", boost: 10}
  {name: "tags", boost: 100}
]

To control the fields that are available in search results, add to the lunr configuration in docpad.coffee:

contentFields: [
  {name: "title"}
  {name: "url"}
  {name: "date"}
]

For faceted search, add to the lunr configuration in docpad.coffee:

facetFields: [
  {name: "tags", label: "Filter by tag"}
  {name: "type", label: "Filter by type"}
]

(Note: the faceted search is not part of Lunr, just my own poor-man's version. Also, you may want to put in a bit of CSS to highlight the "active" facet filters, such as: <style>.active:after{content:'*';}</style>.)

To provide an Eco template for the search-results, add to the lunr configuration in docpad.coffee:

resultsTemplate: 'src/partials/teaser.html.eco'

Then in src/partials/teaser.html.eco:

<div>
  <a href="<%= post.url %>"><%= post.title %></a>
  <span>posted on <%= post.date %></span>
</div>

Or provide a template function for search results directly in docpad.coffee:

resultsTemplate: (context) ->
  post = context.post
  return """
  <div>
    <a href="#{post.url}">#{post.title}</a>
    <span>posted on #{post.date}</span>
  </div>
  """

To add your own "stopwords" to prevent certain words from being indexed, add to the index's configuration in docpad.coffee

stopWords: ['an','array','of','words']

Advanced usage

If you want to make your own UI (and your own implementation of facets), here are the basics:

<script src="/lunr/lunr.min.js" type="text/javascript"></script>
<script src="/lunr/lunr-data-myindex.js" type="text/javascript"></script>
<script type="text/javascript">
  lunrdoc.idx = lunr.Index.load(lunrdoc.indexJson);
  var results = lunrdoc.idx.search('this is your user input');
  for (var i in results) {
    var itemData = lunrdoc.content[results[i].ref];
    console.log(itemData);
    var renderedItem = lunrdoc.template({post: itemData});
    console.log(renderedItem);
  }
</script>

Future

  • Currently this plugin is geared towards static sites, and brings everything client-side. Need to allow for dynamic sites to take advantage of having a back-end - ie, keep the index, searching, and content on the back-end.
  • Hopefully if faceted search is added to Lunr proper, re-implement using that
  • Failing that, add more facet types, like dates and numeric ranges
  • Allow for custom pipeline functions