Docusaurus Pagefind search

Static, zero-config search plugin for Docusaurus using the Pagefind static search library. No external services, no added cost.

Features

• Flexible config: get going by adding a single line to your docusaurus.config.ts file and fine-tune it later
• Index auto-generated at build: — uses pagefind's Node API automatically to generate the site index in postBuild
• Lazy-loaded runtime: Pagefind only fetched when the user first interacts with search
• Grouped sub-results: results are grouped by page with individual section matches
• Keyboard shortcut: Ctrl/Cmd+K to focus, Esc to dismiss
• CSS variable theming: inherits Docusaurus Infima variables and works with your light and dark mode settings
• baseUrl support — works correctly on sites served from a subpath
• TypeScript source included — src/ is shipped in the package for swizzling

How it works

At build time, the plugin's postBuild hook uses pagefind's programmatic Node API to crawl the static HTML output and generate a search index inside the build directory. No configuration is needed — Pagefind's defaults align with Docusaurus's output structure.

At runtime, the SearchBar theme component renders in the navbar. The first time the user types a query, Pagefind's JS bundle is lazy-loaded from <baseUrl>/pagefind/pagefind.js. Results are fetched client-side from the static index — no server required. Up to 8 pages are shown, each with grouped sub-results for individual sections.

Requirements

| Dependency | Version | | --- | --- | | Docusaurus | v3.9 (^3.9.0) | | React | 19 | | Node.js | >= 20 |

Installation

npm install docusaurus-pagefind-search

yarn add docusaurus-pagefind-search

Usage

Add the plugin to your docusaurus.config.ts:

const config: Config = {
  // ...
  plugins: [
    'docusaurus-pagefind-search',
  ],
};

That's it. The search bar will appear in the navbar after your next build.

Note: Search only works after running docusaurus build (or docusaurus build && docusaurus serve). During docusaurus start, there is no Pagefind index, so search results will not appear. Pagefind only indexes static HTML output, which only exists after building your site.

Advanced Configuration

Pass options as the second element of the plugin tuple in docusaurus.config.ts:

plugins: [
  [
    'docusaurus-pagefind-search',
    {
      excludeSelectors: ['.footer', '.hero'],
      forceLanguage: 'en',
    },
  ],
],

Available options

| Option | Type | Description | | --- | --- | --- | | outputSubdir | string | Pagefind output subdirectory (default "pagefind"). Warning: changing this breaks search unless SearchBar is also updated. | | rootSelector | string | CSS selector for the root element to index. | | excludeSelectors | string \| string[] | CSS selector(s) for elements to exclude from indexing. | | glob | string | Glob pattern for files to index. | | forceLanguage | string | Override the detected language for stemming. | | keepIndexUrl | boolean | Keep /index.html in result URLs. | | verbose | boolean | Enable verbose pagefind output. | | logfile | string | Path to a log file for Pagefind output. |

See the Pagefind configuration docs for more details on configuraiton options.

Customizing the search bar

The SearchBar component can be swizzled using the standard Docusaurus mechanism:

npx docusaurus swizzle docusaurus-pagefind-search SearchBar

This copies the TypeScript source into your site's src/theme/SearchBar/ directory which allows customization.

Contributing

Contributions are welcome. Please open an issue or PR.

npm install          # Install dependencies
npm run build        # Compile TypeScript to lib/
npm test             # Run the test suite (vitest)
npm run test:watch   # Run tests in watch mode

Tests use Vitest with happy-dom and cover the plugin's postBuild hook, the flattenResults utility, and the SearchBar React component.

License

MIT view LICENSE