Getting Started

Prerequisites

A Zola site with a content/ directory, and Rust with cargo installed. No wasm toolchain and no npm: the browser runtime ships embedded in the binary.

1. Install

cargo install chops-search --locked

See the installation guide for the bleeding-edge git build.

2. Scaffold

From your site root:

chops-search init

This writes three things, and never overwrites anything that exists:

Re-running init after you've edited the scaffold is safe: it reports what it skipped. Sites that only want the site-wide overlay can pass --no-page to skip the dedicated search page.

3. Fetch the model

chops-search model fetch

This downloads the embedding model (about 30 MB, once) and records exactly what landed in .chops-search/model.lock.json. Commit the lockfile; the model directory itself is already gitignored. This is the only chops-search command that ever touches the network: build reads a directory and nothing else, so a build can never fail because an upstream repo moved.

4. Build

chops-search build

The content tree is walked, chunked, and embedded, and everything lands in static/search/: content-hashed index artifacts plus the wasm engine, worker, page script, and stylesheet. Zola copies static/ verbatim, so the next zola build ships all of it.

Also set this in your config.toml:

build_search_index = false

Zola's own elasticlunr index is dead weight alongside this one.

5. See it

zola serve

Visit /search/ and type. Two things to know about local preview:

• Results appear as you type, with the trailing word matched by prefix.
• zola serve ignores HTTP range requests, so the engine falls back to eager loading. That's a designed degradation, not a bug, but it means you should test range behaviour against a real deploy, not the dev server.

Next steps

Add a search box to every page, set up deployment caching, and then, the part that separates search you trust from search you hope works, measure it.