Switching site search to Algolia, with Netlify build plugin

Switching site search to Algolia, with Netlify build plugin

site search with Algolia backend

Just updated my site search from Simple-Jekyll-Search to Algolia, with the help of Netlify build plugin. In this post, I’ll talk about both of them, just choose the one in your manner.

I have used the Simple Jekyll Search for a long time, the basic idea is to grab the key contents to a JSON file during new Jekyll buildings. No need to configure a server or database, everything leaves to Jekyll and JavaScript.

First, you need to create a template file, for example, ./search.json inside your Jekyll’s root folder. With the help of Liquid, we can generate a valid JSON file with the following template:

layout: null
  {% for post in site.posts %}
      "title"    : "{{ post.title | escape }}",
      "category" : "{{ post.category }}",
      "tags"     : "{{ post.tags | join: ', ' }}",
      "url"      : "{{ site.baseurl }}{{ post.url }}",
      "date"     : "{{ post.date }}"
    } {% unless forloop.last %},{% endunless %}
  {% endfor %}

Since I used collections for my site, I included posts inside collections with:

layout   : null
  {% for collection in site.collections %}
  {% assign col = collection.label %}
  {% if forloop.last %}
    {% for post in site[col] %}
      "title"    : "{{ post.title | escape }}",
      "category" : "{{ post.categories | join: ', ' }}",
      "tags"     : "{{ post.tags | join: ', ' }}",
      "url"      : "{{ post.url }}",
      "content"  : "{{ post.description | strip_html | strip_newlines | remove_chars | escape }}"
    }{% unless forloop.last %},{% endunless %}
    {% endfor %}
  {% else %}
    {% for post in site[col] %}
      "title"    : "{{ post.title | escape }}",
      "category" : "{{ post.categories | join: ', ' }}",
      "tags"     : "{{ post.tags | join: ', ' }}",
      "url"      : "{{ post.url }}",
      "content"  : "{{ post.description | strip_html | strip_newlines | remove_chars | escape }}"
    {% endfor %}
  {% endif %}
  {% endfor %}

Please validate the generated JSON file before fetching data from it, just make sure the template is robust for production.

Also, you can minify this JSON file with gulp, to reduce the file size… I’ve configured my Jekyll to generate files into public folder.

const gulp = require('gulp');
const jsonminify = require('gulp-jsonminify');

gulp.task('minify-json', () => {
  return gulp.src('public/**/*.json')

Next, setup the front-end with HTML/CSS/JS. The simplest configuration is just an input field and a ul for results.

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

<!-- scripts to set search -->
<script src="https://cdn.jsdelivr.net/npm/simple-jekyll-search@1.10.0/dest/simple-jekyll-search.min.js"></script>
  var sjs = SimpleJekyllSearch({
    searchInput: document.getElementById('search-input'),
    resultsContainer: document.getElementById('results-container'),
    json: '/search.json'

Try the rough but working demo below, you can further style it with CSS.

    More options for SimpleJekyllSearch could found at https://github.com/christian-fei/Simple-Jekyll-Search.

    Truly simple and straightforward of this JavaScript library. But the issue is that you have to maintain the search.json file. As long as your posts number grows, the file size grows. And every user needs to load this file for querying data. That’s why I’ve decided to switch to Algolia.

    Until recently, I found that the Netlify platform has published a series of build plugins, including the Algolia Netlify plugin.

    Also, this is the very first plugin I’ve tried on Netlify 🥳.

    One advantage of this plugin is that after setup, the search results will evolve with your website contents. Each time you publish a new version of your site, this plugin triggers a crawler that browses and extracts your website’s contents and pushes them to Algolia.

    Netlify Algolia plugin working flow

    Although Jekyll plugins such as jekyll-algolia have similar features, Netlify’s plugin makes this process more smooth.

    Install the plugin

    First, go to the Algolia Crawler for Netlify and click Sign in to Algolia with Netlify. Algolia automatically creates a new account if you don’t already have one.

    Then, allow Algolia to access your Netlify account. The plugin solely updates your plugin settings and adds necessary environment variables.

    In the Crawler Admin Console, search for your site, then click Install. Algolia automatically updates your Netlify site to add the environment variables (prefixed by ALGOLIA_) that you need to use the plugin. Algolia also creates an application with a dedicated Free plan.

    You can customise the domain name inside the netlify.toml:

    # Algolia search
    package = "@algolia/netlify-plugin-crawler"
      branches = ['*']
      disabled = false
      customDomain = "frankindev.com"


    With the plugin installed, each Netlify deploy triggers a crawl and populates an Algolia index.

    When it receives a build hook, the Algolia Crawler processes your website asynchronously. This operation takes some time, resulting in a short delay between the first deployment and the associated crawl (acceptable 👌).

    You can find information about your current crawler in the Netlify deploy logs.

    Once the crawl is done, you can check your Algolia index, which has the extracted records. Algolia applies a standard relevance configuration by default, but you can fine-tune it as you want in the index settings.

    Well, that’s all for the Netlify build plugin configuration. Let’s move back to our Jekyll side.

    Setup the front-end bundle

    You can find an HTML code snippet in the Crawler Admin Console that you can directly use in your code. Make sure to replace the variables with the provided ones:

    • YOUR_ALGOLIA_APP_ID: the unique identifier of your Algolia application
    • YOUR_ALGOLIA_API_KEY: your Algolia search-only API key)
    • YOUR_NETLIFY_SITE_ID: the unique identifier of your Netlify site (Algolia pre-fills this for you in the snippet from the Crawler Admin Console)
    • YOUR_TARGET_GIT_BRANCH: your target Git branch, either a fixed one (like main) or a dynamic one using process.env.HEAD. See Using multiple branches of the front-end documentation.
    <script src="https://cdn.jsdelivr.net/npm/@algolia/algoliasearch-netlify-frontend@1/dist/algoliasearchNetlify.js"></script>
        appId: '<YOUR_ALGOLIA_APP_ID>',
        apiKey: '<YOUR_ALGOLIA_API_KEY>',
        siteId: '<YOUR_NETLIFY_SITE_ID>',
        branch: '<YOUR_TARGET_GIT_BRANCH>',
        selector: 'div#search',

    This code automatically creates a new input in the specified selector with a ready to use autocomplete, using your newly created Algolia index. So, don’t forget to setup a new div in your Jekyll template where you’d like to have the search input field.

    You can also further customise the styles of the search box, please refer to the full documentation to configure this front-end plugin.

    This front-end plugin also works well on small size screens. It will automatically span to a full page widget by default when you touch/focus on the input field. Still, refer to the full documentation to customise this feature.

    A tiny note for proxying the Algolia search indexes:

    You can self-host the algoliasearchNetlify.js and replace the hosts in the file, some snippets like

    url: "".concat(t, ".algolia.net")

    where t is your appId. You can replace it with empty string such as url: "".concat("", "proxy.example.com"). Currently, there are other 3 urls in the JavaScript file, replace all the fields with the domain name of algolianet.com to your proxied endpoint.


    Now, searching for content inside my site is easy thanks to Algolia engine. The results are more complex and accurate than the simple JSON way, and yet I still don’t need to care about the backend and database.

    Anyway, happy JAMstack and keep healthy…

    Ads by Google


    Frank Lin

    Hey, there! This is Frank Lin (@flinhong), one of the 1.41 billion . This 'inDev. Journal' site holds the exploration of my quirky thoughts and random adventures through life. Hope you enjoy reading and perusing my posts.


    Using Liquid in Jekyll - Live with Demos

    Web Notes


    Using Liquid in Jekyll - Live with Demos

    Liquid is a simple template language that Jekyll uses to process pages for your site. With Liquid you can output complex contents without additional plugins.

    Hands on IBM Cloud Functions with CLI



    Hands on IBM Cloud Functions with CLI

    IBM Cloud CLI allows complete management of the Cloud Functions system. You can use the Cloud Functions CLI plugin-in to manage your code snippets in actions, create triggers, and rules to enable your actions to respond to events, and bundle actions into packages.

    Setup an IKEv2 server with strongSwan



    Setup an IKEv2 server with strongSwan

    IKEv2, or Internet Key Exchange v2, is a protocol that allows for direct IPSec tunnelling between networks. It is developed by Microsoft and Cisco (primarily) for mobile users, and introduced as an updated version of IKEv1 in 2005. The IKEv2 MOBIKE (Mobility and Multihoming) protocol allows the client to main secure connection despite network switches, such as when leaving a WiFi area for a mobile data area. IKEv2 works on most platforms, and natively supported on some platforms (OS X 10.11+, iOS 9.1+, and Windows 10) with no additional applications necessary.


    Ads by Google