docusaurus-search-local

docusaurus-search-local is a Docusaurus plugin and theme that adds full-text search entirely client-side, with no external search service (no Algolia account, no hosted index) required. It builds a search index at build time and ships it with the static site, then provides a search UI theme component powered by lunr/autocomplete.js.

Originally forked from cmfcmf/docusaurus-search-local, it was fully rewritten in TypeScript by easyops-cn with expanded language support, particularly optimized tokenization for Chinese (zh), plus test coverage and CI. It has become the standard offline-search choice for Docusaurus sites that want indexed search without depending on a third-party hosted service.

What You Get

• Build-time search index generation covering docs, blog, and standalone pages
• A drop-in autocomplete search UI theme with keyboard navigation
• Multi-language tokenization, including a dedicated Chinese-language (zh) tokenizer
• No dependency on a hosted search service — the index ships with the static build
• Optional ‘Ask AI’ integration hook for AI-powered answer assistance

Common Use Cases

• Adding search to a self-hosted Docusaurus documentation site without an Algolia account
• Serving documentation to a primarily Chinese-speaking audience with correctly tokenized search
• Air-gapped or internal documentation portals that can’t call out to third-party search APIs
• Small-to-medium docs sites where a hosted search service is unnecessary overhead

Under The Hood

Architecture - The package is split into a server half (src/server/index.ts) that hooks Docusaurus’s plugin lifecycle to crawl generated HTML and build a Lunr-based search index at build time, and a client half (src/client/theme) that swaps in a themed search bar component consuming that prebuilt index via autocomplete.js, with src/shared holding the tokenizer/trimmer logic shared between both halves.

Tech Stack - Written in TypeScript with three parallel tsc build targets (client/server/types), depends on Docusaurus’s own @docusaurus/* utility packages (v2/v3 peer-compatible), @easyops-cn/autocomplete.js for the UI widget, @node-rs/jieba for Chinese word segmentation, cheerio for HTML parsing during index generation, and Lunr for the underlying search index.

Code Quality - 29 .spec.ts test files sit alongside their source modules (e.g. generateTrimmer.spec.ts, lunrLanguageZh.spec.ts), run via Jest with Coveralls coverage reporting in CI; the repo also ships two example Docusaurus sites (website/, website-multi-docs/) used both as live demos and as integration-test fixtures for the plugin.

API Design - Integration is a single plugin/theme pair added to docusaurus.config.js with a typed options object (declared in src/shared/interfaces.ts) covering indexing scope, language, and UI options; because it mirrors Docusaurus’s own plugin/theme convention, existing Docusaurus users face almost no new concepts to learn beyond the plugin’s specific option keys.