Site Search

How search works in zudo-doc and how to configure it.

How Search Works

zudo-doc's built-in search widget uses a client-side word-match scorer for full-text site search. A search index is generated from your content files (title, description, and body text) and served as a single JSON file. The browser loads this index and performs all searching client-side — no server or external service required.

Using Search

Open the search dialog with:

• Keyboard shortcut: Ctrl+K (Windows/Linux) or Cmd+K (macOS)

• Search button: Click the search icon in the header

Type your query and results appear instantly. Click a result to navigate to that page.

Works Everywhere

Search works in all environments:

• Dev mode (pnpm dev): The search index is generated on-the-fly via zfb's devMiddleware

• Production build (pnpm build): The index is written to search-index.json alongside the static site

• Tauri (offline reader): Loads the same index file from the bundled dist/ — no special handling needed

Excluding Pages from Search

Pages with search_exclude: true, draft: true, or unlisted: true in their frontmatter are automatically excluded from the search index.

To explicitly exclude a page, add search_exclude: true to its frontmatter:

---
title: My Internal Page
search_exclude: true
---

Replacing the Search Widget

Use the SearchWidget slot in Host Chrome Bindings to replace the header search widget. The chrome passes exactly these seven locale-aware props:

SearchWidget: (props: {
  placeholderText: string;
  shortcutHint: string;
  resultCountTemplate: string;
  searchLabel: string;
  searchUnavailableText: string;
  loadingIndexText: string;
  noResultsText: string;
}) => unknown;

The chrome binds the site base path internally. A host widget never receives base, so do not require it in the replacement component.

Search Features

The built-in widget provides:

• Word matching: Matches query terms in titles, descriptions, and body text

• Field scoring: Title matches add 3 points, descriptions add 2, and body text adds 1

• Multiple terms: Scores accumulate across matching terms and fields

• Instant results: The full index is loaded once and queried in-memory

Server-Side Search (Search Worker)

For large documentation bases or programmatic API access, zudo-doc provides an optional Search Worker -- a Cloudflare Worker that runs MiniSearch server-side.

When to Use the Search Worker

The built-in client-side search works well for small-to-medium documentation sites. The Search Worker becomes useful when:

• Large index size -- the full search-index.json is too large for comfortable browser download

• API consumers -- bots, CLI tools, or integrations need search access without a browser

• Server-side processing -- you want to keep the search index off the client

How It Works

The Search Worker fetches the same search-index.json from your deployed site and caches it with a 5-minute TTL. It uses MiniSearch with prefix, fuzzy, and field-boost settings; its matching behavior is independent from the built-in widget's word-match scorer.

Comparison

For setup instructions, API documentation, and deployment details, see the Search Worker API reference.