Docs Search: Hosted Indexing vs Static Build-Time Search

Quick answer: Docs search is a core navigation feature, not an add-on, and the choice between a hosted search index and build-time static search is really a decision about infrastructure, privacy, and lock-in. Hosted search indexes content automatically and scales with ranking features, but it depends on a third-party service and sends query data off-site. Static search generates an index at build time and runs entirely in the browser, with no external service and no query data leaving the page, at the cost of some ranking sophistication and a larger index for very big sites. The right choice depends on the size of the documentation and whether the team wants search to depend on an external platform.

Developers reach for docs search within seconds of landing on a reference page, and a weak or slow search undermines even well-written content. The hosted route is convenient: a crawler builds the index, typo tolerance and analytics are included, and the site just embeds a widget. The trade-off is that a useful feature now depends on an external service being available, and every query is visible to that provider. Static search keeps the feature self-contained but requires the team to choose a generator and manage index size as the docs grow. Both can deliver a good experience; they differ in what the team is willing to depend on.

Hosted search versus static build-time search

The two approaches split clearly along operational and privacy lines.

Dimension	Hosted search	Static search
Index built	By crawler/service	At build time
Runtime dependency	External service	None, runs in browser
Query data	Sent to provider	Stays on the page
Ranking features	Advanced, typo tolerant	Good, lighter weight
Index size handling	Server-side	Downloaded or sharded
Analytics	Built in	Self-hosted or none

Generate a static index at build time

A static generator walks the documentation and emits a compressed index the page loads, with queries executed entirely client-side and no external call.

# build a search index from the docs as part of the static build # the output is a self-contained file deployed with the site build-search \ --content ./docs \ --output ./public/search-index.json \ --fields title,headings,body \ --min-length 2 # the page loads the index and runs queries in the browser; # no request is sent to a third-party search provider // minimal client-side query against the generated index const index = await fetch("/search-index.json").then((r) => r.json()); function search(query) { const q = query.toLowerCase(); return index .filter((doc) => doc.terms.some((term) => term.startsWith(q)) ) .slice(0, 10) .map((doc) => ({ title: doc.title, url: doc.url })); }

Manage index size deliberately

For large documentation, a single downloaded index becomes heavy, so shard the index by section or lazy-load it on first interaction rather than shipping everything up front. Compression and stripping the body down to indexed terms keep the payload small. If the site grows beyond what static search can comfortably handle, a self-hosted search service is a middle ground that keeps data on infrastructure the team controls without returning to a third-party widget.

Keep the source of truth and the search aligned

A local-first workflow generates the static index from the same content and spec that produce the docs, so the search is rebuilt on every change and can never point to a removed page. Running the index build in CI means a broken search fails the build rather than silently returning stale results. The durable principle is to treat search as part of the deliverable rather than an external dependency: pick the approach that matches the documentation size, and keep the index derived from the content so the feature stays accurate and portable.

Frequently asked questions

Is static search good enough for a large reference site?

It is, with sharding and compression, up to a size where a single index becomes unwieldy. Beyond that, a self-hosted search service keeps the data in-house while scaling better.

What do I lose by giving up hosted search analytics?

You lose built-in query and click analytics, though self-hosted page analytics can still measure what people search. The trade-off is keeping query data on the page rather than sending it to a provider.

Does static search handle typos and synonyms?

Client-side libraries offer typo tolerance and synonym maps, but generally with less sophistication than a hosted ranking engine. Evaluate the real queries the docs receive before deciding.

How do I prevent stale results after a page moves?

Generate the index from the current content in the same build that deploys the docs, so removed pages and changed URLs are reflected automatically and broken links never enter the index.

This is part of the Powerduck vs Mintlify comparison — start there for the full decision around documentation platforms.