Client-Side-Search

Right, Algolia DocSearch. Let’s get this out of the way: this is the “it just works” option, provided you qualify for the free tier. It’s a hosted service Algolia generously offers for open-source and documentation sites. Think of it as the concierge of search: they handle the heavy lifting of indexing, updating, and hosting the search engine itself. You just plug in the UI. The magic—and the potential pitfall—happens on their servers. A custom crawler (which they run) visits your site according to a schedule you configure, sucks up all the content, and pushes it to an Algolia index. Your JavaScript then queries that index directly. This is fantastic because it means no build-time slowdowns and your search index is always up-to-date with your latest published content. The trade-off? You surrender control. You can’t index unreleased content, and your search is wholly dependent on their crawler and infrastructure.

Alright, let’s talk about Pagefind. If you’ve just wrestled Lunr.js or Fuse.js into submission, you’re going to look at Pagefind and wonder if it’s a prank. It feels like cheating. Why? Because it does the one thing they don’t: it happens after you build your site. While the others are client-side libraries you have to manually feed a JSON index you built during your Hugo build, Pagefind takes the opposite approach. It’s a post-processing step. You let Hugo do its thing, spit out a beautifully complete set of static HTML files, and then Pagefind comes along, reads your entire public directory, and builds a search index from the actual final output. This is its killer feature. It means it indexes exactly what your users see, CSS classes and all. No more wrestling with .Plain or .Summary in your index template to avoid dumping Markdown cruft into your searchable content. It just reads the HTML.

Alright, let’s talk about Fuse.js. If Lunr.js is the meticulous librarian who needs everything indexed and catalogued just so, Fuse.js is the brilliant, slightly scatterbrained friend who can find your lost keys by vaguely describing the general area you might have left them in. It’s a fuzzy search library, and “fuzzy” is the operative word here. It doesn’t need a pre-built index; it just takes your content and a search term and, through a kind of textual witchcraft, finds matches even when the words are misspelled, out of order, or just kinda-sorta similar.

Right, so you’ve decided you want search on your Hugo site. Good for you. It’s a fantastic feature, but let’s be clear: Hugo doesn’t give you a search button to click. You have to build the engine yourself. It’s like buying a fancy car frame and being handed a box of engine parts. Let’s get our hands greasy. The first and most “classic” way to do this is with Lunr.js. It’s a pure JavaScript, in-browser, full-text search library. The big idea is simple but powerful: during your site build, Hugo generates a massive JSON file containing the text of every page you want to search. Then, when a user visits your site, their browser downloads this JSON file, Lunr.js loads it, builds a search index right there in their browser, and then queries that index. No server required. Neat, huh?

Right, so you’ve decided to build a search function for your Hugo site. Good for you. It’s the single best feature you can add to a static site that’s grown beyond a handful of pages. But Hugo, in its infinite wisdom, doesn’t ship with a built-in search. It gives you the ingredients—your content—and expects you to bake the cake yourself. The first and most crucial step is creating the index, a JSON file that our search libraries can actually understand. Think of it as the map to your treasure trove of content. No map, no treasure.

Alright, let’s get our hands dirty. Client-side search in Hugo is a bit of a magic trick. We’re going to pre-build a search index—a highly structured JSON file that’s basically a map of every word on your site and where it lives—and then we’ll teach a JavaScript library how to read that map to find what you’re looking for, all without ever bothering a server. It’s fast, it’s static, and it’s surprisingly powerful.