How to add search functionality to a static web site

Hugo a static web site generator and lunr.js

Since version 0.20 Hugo has a build in capability to create a (customized) index file of available markdown documents down below the content directory tree.

Once this index file is available, we can use lunr.js - a jquery based javascript - to implement a search functionality. The search result pops up instantly, while the user is typing… - pretty neat!

What follows is a brief description to get the whole thing up and running.

Configuration setting (config.toml)

  • Make sure, to have the most recent hugo version installed, at least V0.20 is required. You might want to run: hugo version just to be sure.

  • Add the following to your config.toml configuration file:

    home = [ "HTML", "RSS", "JSON"]
  • Note: Make sure to locate the required index.json file in the layouts folder. Once the file exists, hugo is going to dump the index to file.

    The index.json file looks like:

    [{{ range $index, $page := .Site.RegularPages }}
    {{- if ne $page.Type "json" -}}
    {{- if and $index (gt $index 0) -}},{{- end }}
    	"__comments": "// hugo interface has changed since hugo v0.59: old: .Site.Pages new: .Site.RegularPages",
    	"uri": "{{ $page.Permalink }}",
    	"title": "{{ htmlEscape $page.Title}}",
    	"tags": [{{ range $tindex, $tag := $page.Params.tags }}{{ if $tindex }}, {{ end }}"{{ $tag| htmlEscape }}"{{ end }}],
    	"description": "{{ htmlEscape .Description}}",
    	"content": {{$page.Plain | jsonify}}
    {{- end -}}
    {{- end -}}]

Once this is done, hugo generates a lunrjs index.json at the root of your public folder. If you encounter some problems run: hugo --verbose and check messages and warnings.

Web site configuration:

  • ../layouts/partials/header.html

    Typically, that’s where the css files are:

    {{ if not .Site.Params.disableSearch }}
    	<link href="{{ .Site.BaseURL }}css/auto-complete.css" rel="stylesheet">
    {{ end }}
  • ../layouts/partials/scripts.html

    Please note: as lunr.js is based on jquery, make sure jquery.js gets loaded 1st.

    <!-- custom search -->
    {{ if not .Site.Params.disableSearch }}
    	<script type="text/javascript" src="{{ .Site.BaseURL }}js/lunr.min.js"></script>
    	<script type="text/javascript" src="{{ .Site.BaseURL }}js/auto-complete.js"></script>
    	<script type="text/javascript">
    		var baseurl = "{{ .Site.BaseURL }}";
    	<script type="text/javascript" src="{{ .Site.BaseURL }}js/search.js"></script>
    {{ end }}
  • and finally, add a search entry box somewhere in your webpage layout:

    {{ if not .Site.Params.disableSearch }}
    	<li class="dropdown">
    		<i class="fa fa-search"></i>
    		<div class="searchbox pull-right">
    		<input data-search-input id="search-by" type="text">
    {{ end }}

That’s it.