Customising the search

Use this topic when you need to change the settings of the default search integration.

This template uses offline search from @easyops-cn/docusaurus-search-local. The search box and the /search results page both come from that plugin.

Plugin reference

Full option list and upstream notes: easyops-cn/docusaurus-search-local.

Testing search locally

The local search index is built at production build time.
With pnpm start / docusaurus start, the search index is unavailable. To try search locally, run pnpm build, then pnpm serve.

Template configuration

Search is registered as a theme in docusaurus.config.js:

docusaurus.config.js

themes: [
  [
    '@easyops-cn/docusaurus-search-local',
    {
      hashed: true,
      language: ['en'],
      indexDocs: true,
      indexBlog: false,
      indexPages: false,
      docsRouteBasePath: '/docs',
      searchResultContextMaxLength: 150,
    },
  ],
],

Option	Template value	Meaning
hashed	true	After you publish updated docs, browsers load the new search data instead of an old cached copy
language	['en']	Treat content as English when building search matches
indexDocs	true	Include topics under docs/ in search
indexBlog	false	Skip blog posts (this template has no blog)
indexPages	false	Skip standalone pages under src/pages/
docsRouteBasePath	'/docs'	Must match the docs URL path
searchResultContextMaxLength	150	How many characters of text to show around a match in each snippet

Localising the search

If you add Docusaurus locales, update the search plugin language list to match the languages you index, for example language: ['en', 'de'] for English and German. Use the same language codes the plugin supports (see the plugin README and lunr-languages).

Keep search language in line with your i18n.locales setup in docusaurus.config.js, then rebuild so the search index picks up the change.

Other useful plugin options (defaults apply unless you set them):

Option	Default	Meaning
searchResultLimits	8	Change the number of hits in the navbar dropdown
highlightSearchTermsOnTargetPage	false	Highlight matched terms after you open a result
explicitSearchResultPath	false	In the navbar dropdown, show a full breadcrumb under each hit (category › page › section) instead of only the page title
ignoreFiles	[]	Leave whole pages out of search, for example a draft URL path, or a pattern such as /docs/internal/
ignoreCssSelectors	[]	Leave parts of a page out of search, for example .theme-doc-footer or a custom “do not index” block

Disabling local search

If you want Algolia DocSearch, another plugin, or no search at all:

1. Remove the @easyops-cn/docusaurus-search-local entry from the themes array in docusaurus.config.js.

2. Remove the package if nothing else needs it:

   pnpm remove @easyops-cn/docusaurus-search-local

3. Delete this template’s Search page override if you no longer need it: src/theme/SearchPage/.

4. Wire up the replacement (for example Algolia DocSearch under themeConfig.algolia), or leave search unset.

Restart the dev server (or rebuild) after changing themes.

Changing the search results page

The full results UI lives at /search. Upstream, the plugin hard-codes a short snippet length on that page. This template swizzles the page so behaviour stays aligned with docusaurus.config.js and with authoring needs:

File	Role
src/theme/SearchPage/SearchPage.jsx	Results list: titles, breadcrumbs, summaries, highlighting
src/theme/SearchPage/SearchPage.module.css	Layout and typography for the results page
src/theme/SearchPage/index.js	Theme entry that exports the page

Changing summary length

Each result on /search shows a short text snippet around the match. This template sets the length to 150 characters.

1. Open docusaurus.config.js.
2. Set searchResultContextMaxLength to the length you want.
3. Open src/theme/SearchPage/SearchPage.jsx.
4. Confirm the summary call uses searchResultContextMaxLength in highlightStemmed.

highlightStemmed(
  document.t,
  getStemmedPositions(metadata, "t"),
  tokens,
  searchResultContextMaxLength,
)

info

If you replace SearchPage.jsx with a fresh copy from the plugin, restore that argument. The upstream page hard-codes 100 and does not read the config option.

Showing section titles in search results

By default, the plugin uses the matching section heading as the result title, such as an H2 or H3. This template uses the page H1 instead. The link still opens the matching section when a hash exists.

To show section headings again:

1. Open src/theme/SearchPage/SearchPage.jsx.
2. Find the articleTitle logic in SearchResultItem.
3. Change it to use the section title from the search document, as in the upstream plugin.

Term highlighting on the results page

Matched terms on /search are wrapped in <mark>.

To change how those marks look:

1. Open src/theme/SearchPage/SearchPage.module.css.
2. Add rules for mark inside the result title and summary:

src/theme/SearchPage/SearchPage.module.css

.searchResultItemSummary mark,
.searchResultItem h2 mark {
  background: rgba(79, 38, 131, 0.15);
  color: inherit;
}

If you style from src/css/custom.css instead, use a simple selector such as .container article mark. Do not copy class names from the browser inspector on the built site. Those names are generated at build time and can change, so your styles would stop working.

Term highlighting in topic pages

You can also highlight matches in the topic after the reader opens a result.

1. Open docusaurus.config.js.
2. In the search plugin options, set highlightSearchTermsOnTargetPage: true.
3. Rebuild the site so the client bundle picks up the option.

The plugin then adds highlight query parameters to result links and marks matching terms on the opened page.

Styling the search results dropdown

The navbar dropdown is the plugin’s SearchBar theme (CSS modules). You can restyle it without swizzling by setting the documented CSS variables in src/css/custom.css:

src/css/custom.css

:root {
  --search-local-modal-width: 560px;
  --search-local-modal-background: #f5f6f7;
  --search-local-hit-height: 56px;
  --search-local-highlight-color: var(--ifm-color-primary);
  --search-local-muted-color: #969faf;
  --search-local-hit-color: #444950;
  --search-local-input-active-border-color: var(--ifm-color-primary);
}

Variable	Controls
--search-local-modal-width	Dropdown width
--search-local-modal-background	Dropdown background
--search-local-hit-height	Height of each suggestion row
--search-local-highlight-color	Highlighted match colour in suggestions
--search-local-muted-color	Secondary text (paths, icons)
--search-local-hit-color	Main suggestion text colour

For dark mode, set the same variables under [data-theme='dark'].

For layout changes the variables cannot cover (for example wrapping long snippets in the dropdown), swizzle @easyops-cn/docusaurus-search-local → SearchBar, or override hashed classes carefully from custom.css. Prefer variables first.

Dropdown hit count is searchResultLimits in the plugin options (default 8), separate from searchResultContextMaxLength.

Related content

• Branding the portal
• Customising the home page
• Customising the template
• Plugin README
• Docusaurus search