Written by Edd Turtle on makewithhugo.com
on
(Updated: )

Add Search To A Hugo Site

As with many sites these days, once they get beyond a certain size then search becomes an essential part of them. It can however, be one of the trickier parts of a statically built website because without a back-end to do the search for you, it has to be done client-side in the web browser using JavaScript.

Luckily, solutions to this problem already exist and we show off one these solutions below which uses both FuseJS and MarkJS. This code is based on a gist by eddiewebb - but is built with “vanilla” JavaScript instead of jQuery.

HTML - Search Form

We need a html form to search with. This can either be on a search page of it’s own, any group of pages or all pages - as it works by submitting the form to the /search endpoint. We need the id attribute on the input to put the search query back into it when it loads.

1
2
3
4

<form action="/search" method="GET">
    <input type="search" name="q" id="search-query" placeholder="Search....">
    <button type="submit">Search</button>
</form>

Page - content/search/_index.md

Create a page for us to use as our search form and search results page. In the markdown, we specify the layout to ‘search’ and then we create this layout (in the next step) to give us the ability to easily edit the html.

1
2
3
4
5
6

---
title: "Search"
sitemap:
  priority : 0.1
layout: "search"
---

Layout - layout/_default/search.html

Our search page here contains a <div> element for us to add our results into (#search-results), as well as a <div> element to store our loading message (.search-loading). In the layout we also define a template which we will later use in the JS to populate a single search result entry. Finally, we load our JS libraries (from a CDN in this example, but feel free to self-host).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

{{ define "main" }}

<main>
    <div id="search-results"></div>
    <div class="search-loading">Loading...</div>

    <script id="search-result-template" type="text/x-js-template">
    <div id="summary-${key}">
        <h3><a href="${link}">${title}</a></h3>
        <p>${snippet}</p>
        <p>
            <small>
                ${ isset tags }Tags: ${tags}<br>${ end }
            </small>
        </p>
    </div>
    </script>

    <script src="https://cdnjs.cloudflare.com/ajax/libs/fuse.js/6.6.2/fuse.min.js" integrity="sha512-Nqw1tH3mpavka9cQCc5zWWEZNfIPdOYyQFjlV1NvflEtQ0/XI6ZQ+H/D3YgJdqSUJlMLAPRj/oXlaHCFbFCjoQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
    
    <script src="https://cdnjs.cloudflare.com/ajax/libs/mark.js/8.11.1/mark.min.js" integrity="sha512-5CYOlHXGh6QpOFA/TeTylKLWfB3ftPsde7AnmhuitiTX4K5SqCLBeKro6sPS8ilsz1Q4NRx3v8Ko2IBiszzdww==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
</main>

{{ end }}

JS

The main chunk of the code comes as JavaScript for this as we need to bring it altogether. We read the url parameters to get the query then pass that to FuseJS and MarkJS the write the results back to our page.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

var summaryInclude = 180;
var fuseOptions = {
    shouldSort: true,
    includeMatches: true,
    includeScore: true,
    tokenize: true,
    location: 0,
    distance: 100,
    minMatchCharLength: 1,
    keys: [
        {name: "title", weight: 0.45},
        {name: "contents", weight: 0.4},
        {name: "tags", weight: 0.1},
        {name: "categories", weight: 0.05}
    ]
};

// =============================
// Search
// =============================

var inputBox = document.getElementById('search-query');
if (inputBox !== null) {
    var searchQuery = param("q");
    if (searchQuery) {
        inputBox.value = searchQuery || "";
        executeSearch(searchQuery, false);
    } else {
        document.getElementById('search-results').innerHTML = '<p class="search-results-empty">Please enter a word or phrase above, or see <a href="/tags/">all tags</a>.</p>';
    }
}

function executeSearch(searchQuery) {

    show(document.querySelector('.search-loading'));

    fetch('/index.json').then(function (response) {
        if (response.status !== 200) {
            console.log('Looks like there was a problem. Status Code: ' + response.status);
            return;
        }
        // Examine the text in the response
        response.json().then(function (pages) {
            var fuse = new Fuse(pages, fuseOptions);
            var result = fuse.search(searchQuery);
            if (result.length > 0) {
                populateResults(result);
            } else {
                document.getElementById('search-results').innerHTML = '<p class=\"search-results-empty\">No matches found</p>';
            }
            hide(document.querySelector('.search-loading'));
        })
        .catch(function (err) {
            console.log('Fetch Error :-S', err);
        });
    });
}

function populateResults(results) {

    var searchQuery = document.getElementById("search-query").value;
    var searchResults = document.getElementById("search-results");

    // pull template from hugo template definition
    var templateDefinition = document.getElementById("search-result-template").innerHTML;

    results.forEach(function (value, key) {

        var contents = value.item.contents;
        var snippet = "";
        var snippetHighlights = [];

        snippetHighlights.push(searchQuery);
        snippet = contents.substring(0, summaryInclude * 2) + '&hellip;';

        //replace values
        var tags = ""
        if (value.item.tags) {
            value.item.tags.forEach(function (element) {
                tags = tags + "<a href='/tags/" + element + "'>" + "#" + element + "</a> "
            });
        }

        var output = render(templateDefinition, {
            key: key,
            title: value.item.title,
            link: value.item.permalink,
            tags: tags,
            categories: value.item.categories,
            snippet: snippet
        });
        searchResults.innerHTML += output;

        snippetHighlights.forEach(function (snipvalue, snipkey) {
            var instance = new Mark(document.getElementById('summary-' + key));
            instance.mark(snipvalue);
        });

    });
}

function render(templateString, data) {
    var conditionalMatches, conditionalPattern, copy;
    conditionalPattern = /\$\{\s*isset ([a-zA-Z]*) \s*\}(.*)\$\{\s*end\s*}/g;
    //since loop below depends on re.lastInxdex, we use a copy to capture any manipulations whilst inside the loop
    copy = templateString;
    while ((conditionalMatches = conditionalPattern.exec(templateString)) !== null) {
        if (data[conditionalMatches[1]]) {
            //valid key, remove conditionals, leave contents.
            copy = copy.replace(conditionalMatches[0], conditionalMatches[2]);
        } else {
            //not valid, remove entire section
            copy = copy.replace(conditionalMatches[0], '');
        }
    }
    templateString = copy;
    //now any conditionals removed we can do simple substitution
    var key, find, re;
    for (key in data) {
        find = '\\$\\{\\s*' + key + '\\s*\\}';
        re = new RegExp(find, 'g');
        templateString = templateString.replace(re, data[key]);
    }
    return templateString;
}

// Helper Functions
function show(elem) {
    elem.style.display = 'block';
}
function hide(elem) {
    elem.style.display = 'none';
}
function param(name) {
    return decodeURIComponent((location.search.split(name + '=')[1] || '').split('&')[0]).replace(/\+/g, ' ');
}

The Data - layouts/_default/index.json

All the work we’ve done up until now has been front-end workings, but we also need to build a index.json file which will act as our data source (which is fetched from the JS).

1
2
3
4
5

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

Config

Enable our index json file inside the config.toml file (in the root of your project).

1
2

[outputs]
    home = ["HTML", "RSS", "JSON"]

Although there are quite a few steps to the setup, if you follow the changes above you should end up with a working search form (like we do on this site!)

Any issues let us know in the comments.

#search #markjs #fusejs #js #static #frontend #query #form #json
Author Edd Turtle

Edd is a PHP and Go developer who enjoys blogging about his experiences, mostly about creating and coding new things he's working on and is a big beliver in open-source and Linux.

Tweet me! ☕   Buy me a Coffee

Related Posts

  • Add a 404 Not Found Page –
    In an ideal world, every web page would exist, but sometimes links go to pages that doen’t exist. This is why we make “404 - not found” pages. In Hugo you can do the same. Many of our sites are hosted with Netlify which also support these files - automatically returning the correct http status code for them. To make yours, you can add a file into your layouts folder.
  • 99+ Google Pagespeed Score with Disqus –
    If you’re into your front-end web performance you will probably have heard of Google Pagespeed and/or Lighthouse as tools to test and measure how quickly and efficiently you web pages load. This is also something we use here on this site to make your reading as pleasant as possible. But, we also use the online commenting system called Disqus and the two don’t always play nicely together - in that Disqus loads lots of files and takes a while to load.
  • Make a Static Page in Hugo –
    Hugo is built with blogs in mind, and as such the pages you create will often show in the loop of blog posts. But there are times when you want to create pages - which aren’t posts - and you don’t want them to show unless you link to them. We recently came across this scenario when trying to add a privacy policy page. Here’s our solution to the problem (using the privacy policy as an example).