docusaurus-lunr-search

docusaurus-lunr-search is a Docusaurus plugin that generates a fully client-side search index at build time and ships a drop-in Algolia-style search bar, so documentation sites get working full-text search with no external service, API key, or network dependency. It crawls the static HTML output after docusaurus build, extracts headings and content with multi-threaded workers, builds a Lunr.js index, and serves results entirely from static JSON files loaded in the browser.

What You Get

• A getThemePath + postBuild Docusaurus plugin that indexes built HTML pages into a Lunr.js search index with zero external services
• A ready-made React search bar theme component (SearchBar) with autocomplete-style suggestions, keyboard navigation, and optional result highlighting via mark.js
• Multi-threaded document scanning (worker_threads + a progress bar) so indexing scales across CPU cores on large doc sites, with a configurable maxThreads for containerized builds
• Configurable field boosting (title/content/keywords), route include/exclude globs, custom stop words, and versioned-docs awareness out of the box
• Multi-language stemming support for 20+ locales via lunr-languages, including special handling for CJK segmentation

Common Use Cases

• Adding working full-text search to a Docusaurus documentation site without signing up for Algolia DocSearch or paying for a hosted search service
• Shipping search on internal, air-gapped, or offline-deployable documentation where calling out to a third-party search API isn’t an option
• Sites that need multilingual doc search (via lunr-languages) without standing up a dedicated search backend
• Static/JAMstack deployments where every runtime dependency needs to be bundled with the build output

Under The Hood

Architecture — The plugin is a standard Docusaurus plugin module (src/index.js) exporting a factory that wires into three lifecycle hooks: configureWebpack (to generate a per-language Lunr client bundle via utils.generateLunrClientJS), contentLoaded (to expose generated filenames as global plugin data for the client-side search bar), and postBuild (the core indexing pass). postBuild resolves the doc-plugin’s versioned routes via utils.getFilePaths, spins up a pool of worker_threads running html-to-doc.js to parse each built HTML file with rehype-parse/hast-util-select/hast-util-to-text into {title, content, keywords} records, and accumulates them into a Lunr builder before serializing both the raw documents and the compiled index to JSON files in the build output directory. The client-side half lives in src/theme/SearchBar, a swizzled Docusaurus theme component that lazy-loads those JSON files in the browser, feeds them to a client-bundled Lunr instance, and renders results through a DocSearch-style autocomplete UI with optional mark.js highlighting. Tech Stack — Written as native ESM JavaScript (declared via type: module in package.json) targeting Node.js 20+. Core dependencies are lunr (indexing) with lunr-languages for multilingual stemming, unified/rehype-parse/hast-util-to-text/hast-util-select for HTML-to-text extraction, mustache for templating, cli-progress for build-time feedback, and minimatch for route include/exclude glob matching. The React side depends on clsx and autocomplete.js/mark.js bundled through the theme, with @docusaurus/core, react, and react-dom as peer dependencies pinned to Docusaurus 3.9.2+ and React 19. Code Quality — The repository ships a small Mocha test suite (src/__tests__/utils.spec.js) covering the route/file-path resolution helper in utils.js, but the indexing worker logic and the React search bar are not directly unit tested. Code is organized into clearly separated concerns (plugin lifecycle, HTML-to-doc worker, client-side theme), uses .prettierrc/.editorconfig for consistent formatting, and includes defensive checks (e.g. warning when a route’s output file can’t be resolved) rather than failing silently. API Design — Setup is a single line in docusaurus.config.js (plugins: [require.resolve('docusaurus-lunr-search')]), with all further behavior controlled through a flat, well-documented options object (languages, excludeRoutes, includeRoutes, stopWords, highlightResult, fields, maxThreads, etc.) — no code generation, no separate indexing command, and no required schema beyond what’s already in the doc site’s structure, keeping the barrier to a working search box very low.