hugo-search-index0.5.0 • Public • Published
Hugo Search Index
This library contains gulp tasks and a prebuilt browser script that implements search for Hugo static sites. Using this library along with the excellent search-index by Fergie Mcdowall you can create a search page for your static site, without implementing any server-side processing! Since all the searching happens in the browser, you can still host your site on Github Pages or Netlify.
There are two stages to getting your search up and running:
- Using Gulp, generate your search index from your markdown content
- Serve your generated search index from your web server, and include the search.js script on your search page.
Step 1 - generate your search index using gulp
You'll need to install gulp first, along with this library:
$ npm install --save-dev gulp hugo-search-index
build-search-index as a child task.
const gulp =// import search index tasksgulpgulp
hugo-search-index will scan your
content directory for all markdown files, and create a search index around them. It will then gzip this search index and place the resulting file in the
public directory, which is where the rest of your hugo site goes when it's built.
Now build the search index with gulp:
$ gulp build
Step 2 - load your search index in a search page
Now you need to create a search page. Fortunately this is pretty simple. You just need to create a form element and a results table, and add the appropriate IDs to them.
search.js will find them automatically, and process searches for you, showing results.
An example form with bootstrap:
see the examples directory for more info.
search.min.js will automatically download the
search_index.gz file from the root of your server, unpack it in the browser, and run searches whenever the user types something in the search bar. One thing to be careful of is if the
search_index.gz file is very large. Fortunately text compresses very well, and since we're building the search index from your markdown content it doesn't end up getting very big. On my blog where I've been posting monthly since 2014, the search index is only about 600kb gzipped.
search.min.js automatically looks for the following elements:
- A form with id
- An input with
type="search"inside the form
- A table with id
- An element with id
If those exist,
search.min.js will automatically wire up event handlers to the
onsubmit event of the form and will write out search results as
table rows to the
searchResults table. It does no styling - style the form and table as you like!
search.min.js also fires three custom events on the script element itself, which bubble up to the window:
searchIndexLoadedis fired when the
search_index.gzfile is downloaded from the server, unzipped, and loaded into the search-index. Once fired, there is an object on the
window.Store. This can be used to programmatically initiate a search.
searchIndexErroris fired when an unhandled error occurs, either on loading the
search_index.gzfile or during a search. The error is also logged to console.error.
searchIndexResultsis fired when search results come back from the search form, after they have been written to the table. If you don't include a table with ID
searchResults, you can listen to this event to render the search results yourself.
Example hooking up to the events:
You can add data attributes to the script tag in order to pass configuration options to
The data attributes are:
data-search-index: The URL where the search index should be downloaded, if not
data-language: The language of the current page. You can have a search page for each language and only results with this language will be returned.
The object passed to the detail of the
searchIndexResults event is an array of SearchResults objects. These have the following typescript definition:
window.Store object has the following typescript definition:
You can call
window.Store.runSearch('my query', myCallback) to run your own behind-the-scenes search that won't show up in the
searchResults table. If you don't create a form for the script to attach to, you should use this to run your own searches and render
your own results.
npm i hugo-search-index