Client Side Search for your Hugo Blog with Fuse.js

Client Side Search for your Hugo Blog with Fuse.js

Overview

Featured Image is "Search!" by Jeffrey Beall is licensed with CC BY-ND 2.0. To view a copy of this license, visit https://creativecommons.org/licenses/by-nd/2.0/

In an earlier post about migrating from wordpress to self hosted on Azure, I took you through some steps to host a blog on Hugo. But I don't know if you realised the blog didn't have a search function. I couldn't really search for articles! That I felt was a step back from my wordpress blog where I had the ability to search. Not just me, but you know, if anyone ever wants to search for a particular content in my blog, they really didn't have a way to do that, unless google let them search.

This lack of search functionality did bother me.

However, I was more annoyed that I hadn't tailored the light and dark theme of the website based on Solarized colour scheme that I also use for my code editors. Now that was much easier by following override instructions on the Theme's documentation.

I must admit, these things do sound trivial, however, as someone who has never really interacted with Hugo, I did have a bit of trial error to do. Nor did I have much experience overriding css, in this case sass. But it was not too hard considering, I knew sass enough to read and understand.

So while searching for solutions to solve my next problem, I ran into several github gists that suggested ways of making a client side search for a Hugo blog. So I had to try it out myself.

What was I looking for?

I was looking for a way to add search functionality without having to change the build and deploy process that I setup for my blog. So no additional build steps was one criteria.

The other was, I didn't want to host a server or a database to do search on my static blog. It didn't make any sense for a blog like mine, which barely has enough content for you to read in a day!

So if Hugo could generate an index for a website, then maybe I could use that with a client side search engine, that could display the results. But where could that be?

Then I came across an old github gist by eddieweb. This was last updated in 2018, while I'm writing this. It could be a good baseline, to start testing out the concept. I could definitely work on upgrades and tweak the output for my blog. With that in mind, I proceeded. Let us go through some libraries used for this purpose.

Fuse.js

Fuse.js is a lightweight fuzzy-search library with zero dependencies! That's it! Not need of a backend so long as you have the search index on your client. I felt that would suffice. Perfect project for a weekend. Maybe even a few hours!

All you basically need to get started is include the following script tag on your page:

1<script src="https://cdn.jsdelivr.net/npm/fuse.js@6.4.6"></script>

You might have noticed that I chose a specific version. The version you pick is completely upto you. I just pasted the version currently displayed on Fuse.js website.

jQuery

Anyone who has done some web development a decade ago, must have encountered jQuery in one form or another. Extremely useful library with a lot of utility functions to simplify writing functions in javascript.

Mark.js

Mark.js is a cool library to highlight parts of a webpage.

CDN JS

Not a library but a content delivery network. I used cdnjs to include the libraries that I mentioned earlier on the search page.

What theme am I using?

I am using Hugo Clarity on the blog customised to my taste while I am writing this blog. Mentioning this here as some of the styling done on the search page is very specific to this theme.

Changes

content/search.md

Obviously, to allow visitors to your blog to search, you need to give them a search input or a page. Either way you need a page to display the search results. So create a content/search.md file. This can be an empty file with just the bare minimum.

1---
2title: "Search Results"
3sitemap:
4  priority : 0.1
5layout: "search"
6---
7
8nothing here

layouts/_default/search.html

This is the page that renders the search form and the results. This page involves the styling that is necessary for the search page.

  1{{ define "main" }}
  2
  3<div class="grid-inverse wrap content">
  4  <section id="search-form" class="search-section">
  5    <form action="{{ "search" | absURL }}" class="search-form">
  6      <label for="search-query" class="input-label">Search: </label>
  7      <input id="search-query" name="search-query" type="text"/>
  8    </form>
  9    <ul id="search-results" class="posts"></ul>
 10    </ul>
 11  </section>
 12  {{- partial "sidebar" . }}
 13</div>
 14<!-- this template is sucked in by search.js and appended to the search-results div above. So editing here will adjust style -->
 15<script id="search-result-template" type="text/x-js-template">
 16    <li class="post_item">
 17      <div id="summary-${key}" class="excerpt">
 18        <div class="excerpt_header">
 19          <h3 class="post_link">
 20            <a href="${link}" title="${title}">${title}</a>
 21          </h3>
 22        </div>
 23        <div class="excerpt_footer">
 24          <div class="matched-content">
 25            <p>
 26                ${snippet}
 27            </p>
 28            <p>
 29                ${ isset tags }Tags: ${tags}${ end }
 30            </p>
 31            <p>
 32                ${ isset categories }Categories: ${categories}${ end }
 33            </p>
 34          </div>
 35        </div>
 36      </div>
 37    </li>
 38</script>
 39<script src="https://cdnjs.cloudflare.com/ajax/libs/fuse.js/6.4.6/fuse.min.js" integrity="sha512-KnvCNMwWBGCfxdOtUpEtYgoM59HHgjHnsVGSxxgz7QH1DYeURk+am9p3J+gsOevfE29DV0V+/Dd52ykTKxN5fA==" crossorigin="anonymous"></script>
 40<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js" integrity="sha512-894YE6QWD5I59HgZOGReFYm4dnWc1Qt5NtvYSaNcOP+u1T9qYdvdihz0PPSiiqn/+/3e7Jo4EaG7TubfWGUrMQ==" crossorigin="anonymous"></script>
 41<script src="https://cdnjs.cloudflare.com/ajax/libs/mark.js/8.11.1/jquery.mark.min.js" integrity="sha512-mhbv5DqBMgrWL+32MmsDOt/OAvqr/cHimk6B8y/bx/xS88MVkYGPiVv2ixKVrkywF2qHplNRUvFsAHUdxZ3Krg==" crossorigin="anonymous"></script>
 42<script src="{{ "js/search.js" | absURL }}"></script>
 43<style>
 44  .search-section {
 45    max-width: inherit;
 46    overflow: inherit;
 47    word-wrap: break-word;
 48    display: flex;
 49    flex-direction: column;
 50  }
 51  
 52  .search-form {
 53    max-width: inherit;
 54    overflow: inherit;
 55    display: flex;
 56  }
 57  
 58  input[type=text] {
 59    flex-grow: 2;
 60    padding: 12px 15px;
 61    display: inline-block;
 62    border: none;
 63    border-radius: 5px;
 64    box-sizing: border-box;
 65    font-family: 'Open Sans';
 66    font-size: medium;
 67  }
 68
 69  html[data-mode='lit'] input[type=text] {
 70    background-color: #EEE8D5;
 71    color: #000;
 72  }
 73
 74  html[data-mode='dim'] input[type=text] {
 75    background-color:#0D3640;
 76    color: #E0E5E6
 77  }
 78
 79  .input-label {
 80    padding: 12px 20px;
 81    flex-grow: 1;
 82    text-align: right;
 83    font-weight: bolder;
 84  }
 85  
 86  .matched-content {
 87    width: 100%;
 88    word-wrap: break-word;
 89    overflow: auto;
 90    text-overflow: ellipsis;
 91  }
 92  
 93  mark {
 94    word-wrap: break-word;
 95    overflow: hidden;
 96    background-color: orange;
 97  }
 98  
 99  html[data-mode='lit'] .post_item {
100    background-color: #eee8d5;
101  }
102  
103  </style>
104{{ end }}
105

I have included the content here as everything in the file is open for anyone to use and will just work out of the box with hugo clarity theme. You may tweak the colours and other appearance of the elements on the page yourself.

static/js/search.js

This is the core of the search functionality. The script, uses the index, creates a Fuse instance and searches for the query in the search input and parses results and renders the matches on the same page in a way that the word matches are highlighted. I have made several changes to the script as I decided to upgrade the libraries on my search page compared to eddie's original gist.

  1
  2summaryInclude = 60;
  3// https://fusejs.io/api/options.html
  4var fuseOptions = {
  5  shouldSort: true,
  6  includeMatches: true,
  7  threshold: 0.0,
  8  tokenize: true,
  9  location: 0,
 10  distance: 100,
 11  maxPatternLength: 32,
 12  minMatchCharLength: 1,
 13  keys: [
 14    { name: "title", weight: 0.8 },
 15    { name: "contents", weight: 0.6 },
 16    { name: "tags", weight: 0.4 },
 17    { name: "categories", weight: 0.3 }
 18  ]
 19};
 20
 21var searchQuery = param("search-query");
 22if (searchQuery) {
 23  $("#search-query").val(searchQuery);
 24  executeSearch(searchQuery);
 25} else {
 26  $('#search-results').append("");
 27}
 28
 29function executeSearch(searchQuery) {
 30  $.getJSON("/index.json", function (data) {
 31    var pages = data;
 32    var fuse = new Fuse(pages, fuseOptions);
 33    var result = fuse.search(searchQuery);
 34    if (result.length > 0) {
 35      populateResults(result);
 36    } else {
 37      $('#search-results').append("<li>No matches found</li>");
 38    }
 39  });
 40}
 41
 42function populateResults(result) {
 43  var filteredResults = [];
 44  var addedPermalinks = {};
 45  // remove multiple instances of the same page from the result set. 
 46  for (var i=0, len=result.length; i<len; i++){
 47    // exclude search page from search results if the search query was 'search'
 48    if (!addedPermalinks.hasOwnProperty(result[i].item.permalink) && (result[i].item.permalink.match(/\/search\//g) === null)){
 49      filteredResults.push(result[i]);
 50      addedPermalinks[result[i].item.permalink] = result[i].item.permalink;
 51    }
 52  }
 53  $.each(filteredResults, function (key, value) {
 54    var contents = value.item.contents;
 55    var snippet = "";
 56    var snippetHighlights = [];
 57    var tags = [];
 58
 59    if (fuseOptions.tokenize) {
 60      snippetHighlights.push(searchQuery);
 61    } else {
 62      $.each(value.matches, function (matchKey, mvalue) {
 63        if (mvalue.key == "tags" || mvalue.key == "categories") {
 64          snippetHighlights.push(mvalue.value);
 65        } else if (mvalue.key == "contents") {
 66          start = mvalue.indices[0][0] - summaryInclude > 0 ? mvalue.indices[0][0] - summaryInclude : 0;
 67          end = mvalue.indices[0][1] + summaryInclude < contents.length ? mvalue.indices[0][1] + summaryInclude : contents.length;
 68          snippet += contents.substring(start, end);
 69          snippetHighlights.push(mvalue.value.substring(mvalue.indices[0][0], mvalue.indices[0][1] - mvalue.indices[0][0] + 1));
 70        }
 71      });
 72    }
 73
 74    if (snippet.length < 1) {
 75      snippet += contents.substring(0, summaryInclude * 2);
 76      snippet += "...";
 77    }
 78    //pull template from hugo template definition
 79    var templateDefinition = $('#search-result-template').html();
 80    //replace values
 81    var commaSeparatedTags = (value.item.tags) ? value.item.tags.join(', ') : "";
 82    var commaSeparatedCategories = (value.item.categories) ? value.item.categories.join(', ') : ""; 
 83    var output = render(templateDefinition, { key: key, title: value.item.title, link: value.item.permalink, tags: commaSeparatedTags, categories: commaSeparatedCategories, snippet: snippet });
 84
 85    $('#search-results').append(output);
 86  });
 87  $(".excerpt").mark(searchQuery);
 88}
 89
 90function param(name) {
 91  return decodeURIComponent((location.search.split(name + '=')[1] || '').split('&')[0]).replace(/\+/g, ' ');
 92}
 93
 94function render(templateString, data) {
 95  var conditionalMatches, conditionalPattern, copy;
 96  conditionalPattern = /\$\{\s*isset ([a-zA-Z]*) \s*\}(.*)\$\{\s*end\s*}/g;
 97  //since loop below depends on re.lastInxdex, we use a copy to capture any manipulations whilst inside the loop
 98  copy = templateString;
 99  while ((conditionalMatches = conditionalPattern.exec(templateString)) !== null) {
100    if (data[conditionalMatches[1]]) {
101      //valid key, remove conditionals, leave contents.
102      copy = copy.replace(conditionalMatches[0], conditionalMatches[2]);
103    } else {
104      //not valid, remove entire section
105      copy = copy.replace(conditionalMatches[0], '');
106    }
107  }
108  templateString = copy;
109  //now any conditionals removed we can do simple substitution
110  var key, find, re;
111  for (key in data) {
112    find = '\\$\\{\\s*' + key + '\\s*\\}';
113    re = new RegExp(find, 'g');
114    templateString = templateString.replace(re, data[key]);
115  }
116  return templateString;
117}

layouts/_default/index.json

As Eddie mentioned, Hugo apparently builds an index when you build the website. We can configure Hugo to output the index in json format for our consumption and also specifically tweak what parts of it are searchable.

1{{- $.Scratch.Add "index" slice -}}
2{{- range .Site.RegularPages -}}
3    {{- $.Scratch.Add "index" (dict "title" .Title "tags" .Params.tags "categories" .Params.categories "contents" .Plain "permalink" .Permalink) -}}
4{{- end -}}
5{{- $.Scratch.Get "index" | jsonify -}}

This file is probably the only one unchanged from Eddie's original post.

config.toml

1
2[outputs]
3home = ["HTML", "RSS", "JSON"]

This could be in config.toml or in the frontmatter of your custom _index.md

Result

You can now see the result in action on the Search page

I hope this was useful.

comments powered by Disqus