VitePress Pure JS Local Search (No Algolia, No Server)

Tested on: VitePress 1.6.3, Vite 5.4, 340 doc pages, Node 20 Rejected: Algolia DocSearch (approval delay), Pagefind (wanted built-in modal UX)

Enable local search

.vitepress/config.mts:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        detailedView: true,
        miniSearch: {
          options: {
            fuzzy: 0.2,
            prefix: true,
            boost: { title: 4, text: 2, titles: 1 }
          },
          searchOptions: {
            fuzzy: 0.2,
            boost: { title: 4 }
          }
        }
      }
    }
  }
})

Build generates search index at build time — no extra deploy step.

Customize translations

search: {
  provider: 'local',
  options: {
    locales: {
      root: {
        translations: {
          button: { buttonText: 'Search docs', buttonAriaLabel: 'Search' },
          modal: {
            noResultsText: 'No results',
            resetButtonTitle: 'Reset',
            footer: { selectText: 'to select', navigateText: 'to navigate' }
          }
        }
      }
    }
  }
}

Exclude pages from index

Front matter:

---
search: false
---

Error: search modal empty

Local search index not generated

Built with vitepress build but served dist via wrong static server missing JS chunks. Deploy entire .vitepress/dist.

Error: typo-tolerant search too loose

fuzzy: 0.8 returned irrelevant pages. Tuned to 0.2.

Style modal

.vitepress/theme/custom.css:

.VPNavBarSearch .DocSearch-Button {
  border-radius: 8px;
  background: var(--vp-c-bg-soft);
}

Verify

npm run docs:build
npm run docs:preview
# Ctrl+K → search known heading
ls .vitepress/dist/assets/ | grep -i search

Search latency: ~15ms for 340 pages.

Result

Sub-50ms search, zero external API, works offline after first load.