Krate Docs

#Search

Full-text docs search with three interchangeable backends - Pagefind, docfind, or JSON.

The docs plugin ships a full-text search bar with three interchangeable backends. The default and recommended backend is Pagefind - a mature static search library that indexes your built HTML after a production build and serves a chunked, streamed index, so only the pieces a query needs are downloaded. This scales best on large documentation sites.

Krate also ships docfind (Microsoft's Rust-based engine) and a classic JSON index. docfind is what Krate uses during development builds (see Engines), and it remains available for production if you'd rather not depend on Node.

Pressing the search button (or Ctrl/Cmd+K) focuses the search box and opens its result list. Typing queries the configured engine locally and streams the chunks it needs; if the engine can't load (offline, or a dev build) the UI falls back to the JSON index automatically.

Note

In development, krate dev builds the docfind WASM index instead of running Pagefind, because Pagefind's index is a whole-site post-build pass that dev's incremental rebuilds don't re-run. Search therefore works identically while you write, and switches to Pagefind in production.

#Configuration

docs({
  contentDir: "src/content/docs",
  title: "Docs",
  search: {
    enabled: true,        // default: true
    engine: "pagefind",   // "pagefind" (default) | "docfind" | "json"
    maxResults: 8,        // default: 8
    pagefind: {           // only read when engine: "pagefind"
      excludeSelectors: [],      // extra selectors to skip
      includeCharacters: "",     // e.g. "<>" to index code punctuation
      forceLanguage: "",         // ISO 639-1, e.g. "en"
      outputSubdir: "pagefind",  // bundle dir under the output root
      verbose: false,
    },
  },
})
Option Default Description
enabled true Turn the search bar on/off
engine "pagefind" "pagefind" (recommended) runs the Pagefind indexer after production builds; "docfind" builds the embedded WASM index; "json" uses search-index.json only
maxResults 8 Max results shown
pagefind - Options for the "pagefind" engine

#Engines

Krate ships three search backends. The client picks the configured engine and automatically falls back to the next best option if it can't load, so search keeps working in dev, offline, or when an index wasn't built.

Engine When it runs Index location Needs Node?
pagefind (default, recommended) After a production build pagefind/ bundle Yes (npx)
docfind Build, in-process (always used in dev) docs/search/docfind_bg.wasm No
json Build docs/data/search-index.json No

Pagefind is the default backend. It indexes the built HTML after a production build, then serves a chunked, streamed index. It scales better on large sites because only the chunks a query needs are downloaded, and it is a mature, widely used search library.

It is on by default - no configuration required:

docs({ search: { engine: "pagefind" } }) // the default
  • Production only. Pagefind runs as a post-build step (npx pagefind). In krate dev, Krate uses docfind instead, because the index isn't rebuilt on every incremental edit.
  • Node + network required. The first run downloads the Pagefind binary. If npx or the download fails, Krate prints a warning and the client falls back to the built-in JSON search index - the build never fails.
  • Scoped indexing. The docs content wrapper is tagged with data-pagefind-body, so page chrome (navbar, sidebar, table of contents, the search dialog) is not indexed. Use pagefind.excludeSelectors for extras.
  • Reusing Krate's UI. Pagefind's search API is driven by the theme's existing search component, so the look, Ctrl/Cmd+K, keyboard navigation, and .krate-docs-search-* theming are identical across engines. Pagefind's own component UI is not used.
Note

krate build --watch incremental rebuilds do not re-run the Pagefind indexer - run a full krate build to refresh the index.

#docfind

docfind is Microsoft's Rust-based document search engine (FST + FSST + RAKE keyword extraction). Its index is built in-process at build time and embedded into a WASM module, so searching is fully local with zero network round-trips and no Node required.

Krate uses docfind for development builds regardless of the configured engine, and it's also a good choice for production when you want a fully self-contained, pure-Go build:

docs({ search: { engine: "docfind" } })

The index is built in-process and embedded into a WASM module - no CLI dependency and no temp files. See Contributing -> Architecture.

#json

The classic fallback: a plain search-index.json scored in the browser. Always written, and used automatically whenever a richer engine is unavailable.

#Improving results

docfind extracts keywords from titles, categories, and bodies using the RAKE algorithm. Add explicit keywords in frontmatter for pages whose content doesn't capture the right terms:

---
title: Signals
keywords: [reactive, createSignal, createEffect, createMemo, state]
---

Keywords are weighted highest, then title words, then body phrases.

#Customizing the UI

The search assets live in dist/docs/search/ after a build. Search is a theme concern: @krate/base-docs-theme renders its DocsSearch component (combobox input, keyboard navigation, live result count) and styles it with the .krate-docs-search-* classes. Override those classes from your own stylesheet, or render your own search UI against the headless window.__krateSearch API. Ctrl+K (Cmd+K on macOS) focuses the search box by default. Set search.hotkey (for example "/") to change the shortcut, or "off" to disable it.

With i18n enabled the index spans every locale and results are limited to the language of the page being viewed.

Last updated: 2026-11-17

Contributors: Noinkin