docusaurus-search-local: offline search for Docusaurus v2 and v3 sites

The search index is built in the browser, not by a hosted service

docusaurus-search-local is a search plugin and theme for Docusaurus v2 and v3 that runs entirely on the reader's side. The distinction that matters in practice is that there is no external search service in the path: the index is produced at build time, shipped with the site, and queried in the browser, so search keeps working on a network that cannot reach a third party. The project describes itself as an offline or local search plugin and theme, and it states that multiple languages are supported, with the implementation especially optimised for Chinese. That optimisation is the reason the package exists separately from the project it started as. The repository records that it was originally forked from cmfcmf/docusaurus-search-local and later rewritten with TypeScript, with styles polished, Chinese support added and tests covered. A live demo is published on the project pages, and screenshot files for the English and Chinese interfaces are in the repository.

It installs as a theme, not a plugin

The registration step is where most people get stuck, and the reason is a change of design rather than a mistake. The project states plainly that it presents itself as a theme instead of a plugin, and points at a comment on a Docusaurus issue explaining why. In practice that means the package goes into the themes array of your Docusaurus configuration, not into the plugins array, and it is passed a configuration object as the second element of the array entry. The configuration object is typed, and the example annotates it with a type import so editors can check the option names. A minimal registration looks like this:

    [
      require.resolve("@easyops-cn/docusaurus-search-local"),
      /** @type {import("@easyops-cn/docusaurus-search-local").PluginOptions} */
      ({
        // ... Your options.
        // `hashed` is recommended as long-term-cache of index file is possible.
        hashed: true,

        // For Docs using Chinese, it is recomended to set:
        // language: ["en", "zh"],

        // Customize the keyboard shortcut to focus search bar (default is "mod+k"):
        // searchBarShortcutKeymap: "s", // Use 'S' key
        // searchBarShortcutKeymap: "ctrl+shift+f", // Use Ctrl+Shift+F

The package itself comes from npm, and the install step offers npm and yarn as alternatives:

npm install --save @easyops-cn/docusaurus-search-local
# or
yarn add @easyops-cn/docusaurus-search-local

The hashed option decides how the index file is cached

Inside the options object, one setting stands out and it is commented in the example as recommended: hashed, set to true, because it makes long term caching of the index file possible. Without a hash in the file name, a browser or CDN will keep serving an old index after you rebuild the site, and readers will search a stale set of pages. That is the sort of quiet failure that costs hours. The same block shows the other options, most of them commented out. The searchBarShortcutKeymap option overrides the keyboard shortcut that focuses the search bar, whose default is mod+k, with examples such as a single letter or a two key combination. The language option takes an array, and the example suggests en and zh for a documentation set that mixes them. The forceIgnoreNoIndex option exists for sites that use noIndex, where you deliberately want a local index anyway.

Ask AI is opt-in and pulls in a second package

The feature that gets the most attention is also the one with the sharpest boundary. The Ask AI integration is opt-in, and enabling it means installing a separate package, open-ask-ai, in addition to the search theme. The project is explicit that this feature requires an external AI service, and it points at Open Ask AI Server, described as a serverless solution that can be used for free on a Vercel Hobby Plan. In the options the askAi object carries a project name, an apiUrl pointing at a streaming endpoint, and an optional hotkey such as cmd+I that triggers the Ask AI panel. With it enabled, the described behaviour is answers based on your documentation, AI assistance through a keyboard shortcut, and context-aware responses. Note what this means for adoption: the search half of the package is self-contained, while the AI half is a two-project deployment, and the plugin is only the front end of it.

Indexing scope is decided by four options, not by a crawl

There is no crawler and no runtime scan of your routes, so what ends up in the index is decided by configuration. The options table lists indexDocs and indexBlog as booleans that both default to true, and indexPages as a boolean that defaults to false, which tells you that standalone pages are opt-in while docs and blog posts are indexed out of the box. The docsRouteBasePath option takes a string or an array of strings and defaults to the /docs path, with the note that a leading slash is not required. The table also points out that for the docs-only mode of Docusaurus, this value has to match the routeBasePath setting used by the classic preset. That is the kind of detail that quietly breaks a site that mixes docs-only and classic layouts, and it is worth checking against your own configuration before you blame the search.

The upstream fork it came from is the honest comparison

Because the project records its own lineage, the comparison does not require guessing. The original cmfcmf/docusaurus-search-local is the base, and the changes claimed for this fork are a full rewrite in TypeScript, polished styles, support for the Chinese language, and covered tests. Practically, a team that needs Chinese content to be searchable, or that wants a typed options surface and a test suite behind the plugin, is picking a different tool from the one it would have installed from the upstream repository. A team whose documentation is English only and whose search needs are already met gains less, and the maintenance question then becomes which fork they want to track.

A monorepo with two example sites and a yarn workspace build

The repository layout explains how the project develops itself. The root is a private package whose scripts drive a yarn workspace setup, with a start script that runs the start task across all workspaces while excluding the multi-docs example, and matching build scripts for the ordinary build, an i18n build and a preview build, each setting a BUILD_TYPE environment variable through cross-env. There are separate targets for building only the theme and only the website, and the theme has its own workspace command. Testing runs jest with NODE_ENV set to test, linting is handled through eslint with a prettier config, and husky installs on prepare with lint-staged configured for staged files. Two documentation sites exist as examples, a website and a website-multi-docs, which is the pair that exercises the multi-language and multiple-docs-route behaviour. The tooling is pinned through a yarn lock file and updated by renovate, and release-please is configured for the versioned releases.

Editorial conclusion

docusaurus-search-local fits a Docusaurus documentation team that needs search to work without a hosted search service, and that reads or writes Chinese, where the upstream fork it came from did not cover that language well. It does not fit a site that wants a managed search index, or a team that needs the Ask AI answers to come from its own infrastructure without adding the open-ask-ai-server component. Before adopting it, check the option that decides whether pages are indexed, note that the plugin registers itself as a theme in the themes array, and confirm the last push on 2026-07-29 still matches the Docusaurus version you run.

Frequently asked questions

Official sources

1. easyops-cn/docusaurus-search-local on GitHub
2. License: MIT
3. Project website
4. README
5. Releases