How to add lunr.js to your site?


With the help of @ipstenu’s comment on the Search Index .json-file for Lunr.js thread, I got the index.json to generate fine.

But being Javascript-ignorant, I don’t understand how to use to add lunr.js to my site in a way that it ties in with that index.json.

Can someone do a short writeup on how to set up the search frontend on the site that searches using that index.json using lunr.js?

PS: I have already looked at the Live Hugo Site search with Lunr.js tutorial by @rdwatters, but it looks like that is not using Hugo’s output format feature for the .json generation.

I think what confuses most people about this is that you need to generate a Lunr search index (which isn’t the same as the Hugo generated file) – this is some Lunr specific reverse document index. I guess you could let the client do that work, but that would be a waste.

So you need some Javascript step after the Hugo search index build, i.e. Gulp/Grunt or similar. Something ala:

	var data = {
        store: {}

    var idx = lunr(function() {
        this.field('title', {
            boost: 40
        this.field('keywords', {
            boost: 20
        # This is the file generated by Hugo.
        var source = JSON.parse(fs.readFileSync("public/index.json"));

        var that = this;

        source.forEach(function(item) {
            var doc = {
                'title': item.title,
                'keywords': item.keywords,
                'href': item.ref

  [doc.href] = item.title


    data.index = idx

    var serialized = JSON.stringify(data)

    fs.writeFile('static/lunr.json', serialized, done);

OK, I am one of those.

It would be great if there’s some documentation to help set it up. I saw there are npm projects like lunr-hugo (and hugo-lunr), but they too aren’t well documented from my perspective.

Every time I take up the mission to add search to my site, I meet a dead-end. It would be great if someone could do a writeup on start to finish Hugo+lunr.js integration aimed towards folks not familiar with JS (stuff like install foo npm script, run bar command, add toto to your templates, and finally run hugo.)


After some googling, I have quite many resources on this topic now… now just need to digest everything and hopefully come up with a guide to set this up:

  1. Figure out how docdock/hugo-theme-learn themes implements lunr.js based search
  1. Joseph Earl
  1. Half Elf
  1. Hiller
1 Like

I’ve added this functionality to the MemE theme: Compared to the docDock and Learn themes mentioned above, this implementation has some advantages, for example support for non-English languages and reduced bandwidth consumption because the search index is only loaded when needed.

I’ve also written a blog post explaining how one would add this feature to a site without using a theme: