Simple-Jekyll-Search

Simple-Jekyll-Search

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

🚀 Read this guide 📖 to get started!

Use case

You have a blog, built with Jekyll, and want a lightweight search functionality on your blog, purely client-side?

No server configurations or databases to maintain.

Just 5 minutes to have a fully working searchable blog.

---

Installation

npm

npm install simple-jekyll-search

Getting started

Create search.json

Place the following code in a file called search.json in the root of 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: null
---
[
  
    {
      "title"    : "Thai Meatballs with Peanut Sauce",
      "category" : "",
      "tags"     : "",
      "url"      : "/jekyll/update/2019/06/14/thaimeatballs.html",
      "date"     : "2019-06-14 15:04:17 +0000"
    } ,
  
    {
      "title"    : "Fresh Scones",
      "category" : "",
      "tags"     : "",
      "url"      : "/jekyll/update/2019/06/14/scones.html",
      "date"     : "2019-06-14 15:04:17 +0000"
    } ,
  
    {
      "title"    : "Chilli Beef",
      "category" : "",
      "tags"     : "",
      "url"      : "/jekyll/update/2019/06/14/chillibeef.html",
      "date"     : "2019-06-14 15:04:17 +0000"
    } ,
  
    {
      "title"    : "Brownies",
      "category" : "",
      "tags"     : "",
      "url"      : "/jekyll/update/2019/06/14/brownie.html",
      "date"     : "2019-06-14 15:04:17 +0000"
    } ,
  
    {
      "title"    : "White Choc Cookies",
      "category" : "",
      "tags"     : "",
      "url"      : "/jekyll/update/2019/06/06/whitechoccookies.html",
      "date"     : "2019-06-06 02:05:56 +0000"
    } ,
  
    {
      "title"    : "Tomato Risotto with Basil oil",
      "category" : "",
      "tags"     : "",
      "url"      : "/jekyll/update/2019/06/06/tomatorisotto.html",
      "date"     : "2019-06-06 02:05:56 +0000"
    } ,
  
    {
      "title"    : "Okonomiyaki",
      "category" : "",
      "tags"     : "",
      "url"      : "/jekyll/update/2019/06/06/okonomiyaki.html",
      "date"     : "2019-06-06 02:05:56 +0000"
    } ,
  
    {
      "title"    : "Choc Chip Cookies",
      "category" : "",
      "tags"     : "",
      "url"      : "/jekyll/update/2019/06/06/chocchipcookies.html",
      "date"     : "2019-06-06 02:05:56 +0000"
    } ,
  
    {
      "title"    : "Butterscotch Buttons",
      "category" : "",
      "tags"     : "",
      "url"      : "/jekyll/update/2019/06/06/butterscotchbuttons.html",
      "date"     : "2019-06-06 02:05:56 +0000"
    } ,
  
    {
      "title"    : "Bowtie Pasta with Chorizo, Red Capsicum, Rocket & Lemon Ricotta",
      "category" : "",
      "tags"     : "",
      "url"      : "/jekyll/update/2019/06/06/bowtiepastachorizo.html",
      "date"     : "2019-06-06 02:05:56 +0000"
    } ,
  
    {
      "title"    : "Baked Bean Fritters",
      "category" : "",
      "tags"     : "",
      "url"      : "/jekyll/update/2019/06/06/bakedbeanfritters.html",
      "date"     : "2019-06-06 02:05:56 +0000"
    } ,
  
    {
      "title"    : "Welcome to Jekyll!",
      "category" : "",
      "tags"     : "",
      "url"      : "/jekyll/update/2019/06/06/welcome-to-jekyll.html",
      "date"     : "2019-06-06 02:05:56 +0000"
    } ,
  
    {
      "title"    : "Hello World!",
      "category" : "",
      "tags"     : "",
      "url"      : "/jekyll/update/2019/06/06/helloWorld.html",
      "date"     : "2019-06-06 02:05:56 +0000"
    } 
  
]

Preparing the plugin

Add DOM elements

SimpleJekyllSearch needs two DOM elements to work:

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

Give me the code

Here is the code you can use 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)

For example in _layouts/default.html:

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

<!-- script pointing to jekyll-search.js -->
<script src="/simple-jekyll-search.min.js"></script>

<!-- or -->
<script src="https://cdn.rawgit.com/christian-fei/Simple-Jekyll-Search/master/dest/simple-jekyll-search.min.js"></script>

Usage

Customize SimpleJekyllSearch by passing in your configuration options:

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

returns { search }

A new instance of SimpleJekyllSearch returns an object, with the only property search.

search is a function used to simulate a user input and display the matching results. 

E.g.:

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

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

Options

Check out the wiki for the options!

Wiki

Check out the wiki for general discussions.

Development

• npm install
• npm test

Acceptance tests

cd example; jekyll serve

# in another tab

npm run cypress -- run

Contributors

Thanks to all contributors over the years! You are the best :)

@daviddarnes @XhmikosR @PeterDaveHello @mikeybeck @egladman @midzer @eduardoboucas @kremalicious @tibotiber and many others!