Simple-Jekyll-Search

A JavaScript library to add search functionality to any Jekyll blog.

Use case

You have a blog built with Jekyll and want a lightweight search functionality that is:

• Purely client-side
• No server configurations or databases to maintain
• Set up in just 5 minutes

Getting started

Create search.json

Place the following code in a file called search.json in your Jekyll blog. (You can also get a copy from here)

This file will be used as a small data source to perform the searches on the client side:

---
layout: none
---
[
  {% for post in site.posts %}
    {
      "title"    : "{{ post.title | escape }}",
      "category" : "{{ post.category }}",
      "tags"     : "{{ post.tags | join: ', ' }}",
      "url"      : "{{ post.url | relative_url }}",
      "date"     : "{{ post.date }}"
    } {% unless forloop.last %},{% endunless %}
  {% endfor %}
]

Preparing the plugin

Add DOM elements

SimpleJekyllSearch needs two DOM elements to work:

• a search input field
• a result container to display the results

For example with the default configuration, you need to place the following code within the layout where you want the search to appear. (See the configuration section below to customize it)

<!-- HTML elements for search -->
<input type="text" id="search-input" placeholder="Search blog posts..">
<ul id="results-container"></ul>

Usage

Customize SimpleJekyllSearch by passing in your configuration options:

var sjs = SimpleJekyllSearch({
  searchInput: document.getElementById('search-input'),
  resultsContainer: document.getElementById('results-container'),
  json: '{{ "/assets/data/search.json" | relative_url }}',
})

The script and library needs to be imported in the head of your layout, or at the end of the body tag.

returns { search }

A new instance of SimpleJekyllSearch returns an object, with the only property search. The search is a function used to simulate a user input and display the matching results.

var sjs = SimpleJekyllSearch({ ...options })
sjs.search('Hello')

💡 it can be used to filter posts by tags or categories!

Options

Here is a table for the available options, usage questions, troubleshooting & guides:

Option	Type	Required	Description
searchInput	Element	Yes	The input element on which the plugin should listen for keyboard events and trigger the searching and rendering for articles.
resultsContainer	Element	Yes	The container element in which the search results should be rendered in. Typically, a <ul>.
json	String | JSON	Yes	You can either pass in an URL to the search.json file, or the results in form of JSON directly, to save one round trip to get the data.
noResultsText	String	No	The HTML that will be shown if the query didn't match anything.
limit	Number	No	You can limit the number of posts rendered on the page.
strategy	String	No	With 'fuzzy' enables fuzzy search to allow less restrictive matching or 'wildcard' for enhance regex search with similar matching.
exclude	Array	No	Pass in a list of terms you want to exclude (terms will be matched against a regex, so URLs, words are allowed).
success	Function	No	A function called once the data has been loaded.
debounceTime	Number	No	Limit how many times the search function can be executed over the given time window. If no debounceTime (milliseconds) is provided a search will be triggered on each keystroke.
searchResultTemplate	String	No	The template of a single rendered search result. (match liquid value eg: '<li><a href="{{ site.url }}{url}">{title}</a></li>'

Middleware

templateMiddleware (Function) [optional]

A function that will be called whenever a match in the template is found. It gets passed the current property name, property value, and the template. If the function returns a non-undefined value, it gets replaced in the template.

This can be potentially useful for manipulating URLs etc.

Example:

SimpleJekyllSearch({
  // ...other config
  templateMiddleware: function(prop, value, template) {
    if (prop === 'bar') {
      return value.replace(/^\//, '')
    }
  },
})

sortMiddleware (Function) [optional]

A function that will be used to sort the filtered results.

By setting custom values in the search.json file, you can group the results by section or any other property.

Example:

SimpleJekyllSearch({
  // ...other config
  sortMiddleware: function(a, b) {
    var astr = String(a.section) + "-" + String(a.caption);
    var bstr = String(b.section) + "-" + String(b.caption);
    return astr.localeCompare(bstr)
  },
})