Overview

This theme comes with a docs search that is designed for small sites. If your documentation is extensive, you might find an alternative search library works better for your project.

How the Theme Search Works

During the build process, an index of paragraphs and headers is created for each post. These data, along with the post's title and description, are used by gatsby-plugin-elasticlunr-search to build a search index for the site. This index can be fetched using the GraphQL query allSiteSearchIndex.

Only posts living in src/docs (or the docsPath set in the theme options) are indexed.

As a user inputs a search query, this search index is crawled for a match of the exact search query. Matches are ordered based on the following boost values:

searchIndex.search(query, {
  fields: {
    title: { boost: 3 },
    description: { boost: 2 },
    headers: { boost: 2 },
    paragraphs: { boost: 1 },
  },
});

If primaryResultsOnly is set to true, matches in the title, description, and/or headers are presented, but no paragraph matches are included.

For a demonstration, try searching for 'mdx' in the demo site.

Using Algolia or Another Search Interface

There are faster and more robust solutions to documentation search out there. I recommend DocSearch by Algolia, which is free for docs sites.

To use a different search interface,

1. Set allowDocsSearch to false in the gatsby-config.js theme options. This prevents the theme from fully populating the search index and from showing the theme searchbar.

2. Shadow the Search component to create one that works with your custom library. For example, Algolia provides functions and components to display its search results.

3. Shadow the component (e.g., Header) that will display the custom Search component.