Search

SveltePress default theme provides built-in Local Search powered by Pagefind out of the box with zero configuration. In addition, the default theme supports Algolia DocSearch through docsearch and custom search components through search, including @sveltepress/meilisearch.

Local Search (Default)

Local search is enabled by default with zero configuration. When building your documentation site (pnpm build), SveltePress automatically runs Pagefind to index all static HTML pages and bundles the search assets into /pagefind/.

Features

Zero-config: Works immediately without external API keys or remote indexing services.
Offline & Static: Runs entirely in the browser via WebAssembly, fast and privacy-friendly.
Multi-locale support: Automatically detects <html lang="..."> and filters search queries by the active page language.
Keyboard navigation: Opens via Cmd+K (macOS) or Ctrl+K (Windows/Linux), navigate with Arrow keys, select with Enter, close with Escape.
Development notice: In development mode (pnpm dev), searching displays an informative notice explaining that the full index is created during production build.

Disabling Local Search

If you want to disable search entirely:

vite.config.(js|ts)

import {  } from '@sveltepress/theme-default'
import {  } from '@sveltepress/vite'
import {  } from 'vite'

export default ({
  : [
    ({
      : ({
        : false,
      }),
    }),
  ],
})

You can also disable the build-time indexer in the Vite plugin:

vite.config.(js|ts)

import {  } from '@sveltepress/vite'

({
  : false,
})

Algolia DocSearch

Pass a docsearch config object to defaultTheme to use Algolia DocSearch instead of the default local search in the navbar.

Required fields are appId, apiKey, and indexName. Every other DocSearch option is also accepted.

vite.config.(js|ts)

import {  } from '@sveltepress/theme-default'
import {  } from '@sveltepress/vite'
import {  } from 'vite'

export default ({
  : [
    ({
      : ({
        : {
          : 'YOUR_APP_ID',
          : 'YOUR_SEARCH_API_KEY',
          : 'YOUR_INDEX_NAME',
        },
      }),
    }),
  ],
})

Apply for DocSearch

DocSearch is free for open-source documentation sites. Apply at docsearch.algolia.com .

Meilisearch

@sveltepress/meilisearch is the supported Meilisearch search component. Install it first:

npm install --save @sveltepress/meilisearch

Create a wrapper that provides your Meilisearch connection settings:

src/lib/MeilisearchSearch.svelte

<script lang="ts">
  import  from '@sveltepress/meilisearch/Search.svelte'
</script>

<
  ="https://search.example.com"
  ="YOUR_SEARCH_ONLY_KEY"
  ="docs"
/>

svelte

Then pass the wrapper path to the default theme's custom-search hook:

vite.config.(js|ts)

import {  } from '@sveltepress/theme-default'

({
  : '/src/lib/MeilisearchSearch.svelte',
})

The component queries an existing Meilisearch index; it does not build the index for you. Each record should provide id, title, content, and either url or path. Use a search-only API key in browser code.

Production builds

A custom search source path is bundled into static production builds: the theme resolves the configured .svelte path at build time and loads it as a lazy chunk, so no extra runtime configuration is needed. Configure the wrapper as a source path (as above). Passing a component object directly is not supported — theme options are serialized to JSON for the client, so objects are dropped. If a production deployment shows no search, make sure search is a source-path string.

For another search provider, implement the same search hook with your own Svelte wrapper. Search precedence is: custom search component > explicit docsearch > default LocalSearch.

Search across locales and versions

When your site combines i18n locales with version management, search stays per-locale and per-version, and the crawler-facing outputs follow the same URL scheme the site serves (/, /zh/, /bn/, /v/<id>/…, /zh/v/<id>/…).

Locale-aware search

Each locale carries its own theme options, so give each locale its own DocSearch index — the pre-i18n documentation site used one index per language:

vite.config.(js|ts)

import {  } from '@sveltepress/theme-default'
import {  } from '@sveltepress/vite'
import {  } from 'vite'

export default ({
  : [
    ({
      : ({
        // Site-level options shared by every locale (logo, github, pwa, ...)
      }),
      : {
        '/': {
          : 'en',
          : 'English',
          : {
            : {
              : 'YOUR_APP_ID',
              : 'YOUR_SEARCH_API_KEY',
              : 'sveltepress',
            },
          },
        },
        '/zh/': {
          : 'zh',
          : '中文',
          : {
            : {
              : 'YOUR_APP_ID',
              : 'YOUR_SEARCH_API_KEY',
              : 'cn',
            },
          },
        },
      },
    }),
  ],
})

Expand code

The Navbar remounts the DocSearch widget whenever the active index or version changes, so switching locale or version queries the right index.

Version-aware search

A version in the manifest may carry search metadata. While a reader is on that historical version's pages (/v/<id>/…), the theme switches DocSearch to the configured indexName and merges facetFilters into the query:

sveltepress.versions.json

{
  "versions": [
    {
      "id": "2026-08-28",
      "search": {
        "indexName": "sveltepress-v2026-08-28",
        "facetFilters": ["version:2026-08-28"]
      }
    }
  ]
}

json

Keep the crawler's facet tags in sync with this metadata. Historical versions without search show "Search is not available for this documentation version." — for DocSearch, custom search, and the built-in Local Search alike.

Crawling and result URLs

The generated sitemap.xml lists every locale's current pages and every eligible historical version page with hreflang alternates; EOL history is excluded unless the version opts out (noIndex: false), and every version page emits its own rel="canonical" link. Index records must point at these real, prefixed URLs — a Chinese record's url is /zh/guide/…, a frozen version's is /v/2026-08-28/guide/….

Custom search components

The Navbar renders a custom search component only when search is available for the current route, remounts it per version, and passes it two props:

version — the active version object ({ id, label, status, … }), or the current version on unprefixed pages.
versionSearch — the version's search metadata ({ indexName?, facetFilters? }), or null.

When your index stores multiple versions, filter results by the facets in versionSearch. Record URLs must be the full prefixed routes. No locale prop is passed: if you keep one index per locale, read the locale from location.pathname yourself.

Suggest changes to this page