Search for Static Sites

Search is the feature that most often makes teams doubt a static architecture. There is no database to query and no server to run it, so it feels like search must mean a third-party service. It does not. The dominant pattern for static sites is build-time indexing: the build that renders your pages also produces a search index as static files, and the reader's browser runs queries locally against it. The alternative — a hosted service such as Algolia — is a deliberate choice for specific needs, not a requirement.

This topic sits inside Choosing the Right Static Site Generator for Production because search is frequently a deciding factor in framework choice: Starlight ships Pagefind, VitePress ships MiniSearch, Docusaurus defaults to Algolia, and Hugo, Eleventy and Jekyll ship nothing. The comparison of those defaults is in Docs Frameworks: Docusaurus, Starlight and VitePress.

All measurements below use three test corpora — 300 pages, 2,000 pages and 10,000 pages of documentation — built with each tool and queried from a Moto G Power-class device profile in Chrome DevTools with simulated fast 4G.

The Four Tools Worth Considering

Pagefind runs after your build, reads the generated HTML, and writes a chunked index into pagefind/ in the output folder. Its browser library downloads a small entry file, then fetches only the index fragments and page excerpts that match the typed query. It works with any generator because it reads HTML, not your source.

Lunr builds a single inverted index, usually in a build script, serialised to JSON. The browser downloads the whole thing before the first query. It is mature, small in code and easy to reason about, and it scales poorly because the index is monolithic.

MiniSearch is similar in shape to Lunr — one serialised index — with better prefix and fuzzy matching, auto-suggestions and a smaller index format. VitePress bundles it as its local search provider.

Algolia (and the free DocSearch programme for open-source docs) is a hosted search API. A crawler or a CI job pushes records; the browser sends each keystroke to Algolia and receives ranked results in tens of milliseconds, with typo tolerance, synonyms and analytics.

# Pagefind: any SSG, run after the build
npx pagefind --site dist
# → dist/pagefind/pagefind.js, pagefind-ui.js, fragments/, index/

Index Size and First-Query Cost

The cost a reader pays is the download before their first result. For monolithic indexes that is the whole index; for Pagefind it is the entry file plus the fragments the query touches.

Past roughly 1,000 pages, a monolithic index becomes a megabyte-scale download on a phone before the first result, which readers experience as a search box that does nothing for two to four seconds. That threshold is the core of Search Index Size Budgets for Large Docs.

Query Latency and Relevance

Once the index is loaded, local queries are fast: Lunr and MiniSearch answered in 2–8 ms on the 2,000-page corpus, Pagefind in 30–60 ms including fragment fetches on the first keystrokes and under 10 ms once fragments were cached. Algolia answered in 25–70 ms per keystroke depending on distance to the nearest data centre.

Relevance is harder to measure, so we used a test set: the 60 most frequent queries from a production docs site's analytics, each with a known best page. A tool scored a hit when that page ranked first.

Algolia's lead comes from typo tolerance and from ranking tuned on attribute order. Pagefind closes most of the gap with two lines of markup — weighting headings and marking navigation chrome as excluded — shown in Adding Pagefind to an Astro Site.

Performance Impact on the Page

Search should cost nothing until someone searches. The rule for every tool is the same: do not load the search library or index on page load. Render the search box as plain HTML, and on focus or the first keypress, import the library.

<input id="q" type="search" placeholder="Search docs" aria-label="Search docs">
<script type="module">
  const q = document.getElementById('q');
  let pagefind;
  q.addEventListener('focus', async () => {
    pagefind ??= await import('/pagefind/pagefind.js');
    pagefind.preload?.('');
  }, { once: true });
</script>

On a docs page measured with Lighthouse, loading Pagefind's UI eagerly added 38 KB of JavaScript and 90 ms of Total Blocking Time; loading on focus made the page's metrics identical to a page with no search at all. The same lazy-loading approach is covered in general in Third-Party Script Performance on Static Sites, and Algolia's client benefits from it just as much.

Cost and Operations

Build-time tools cost build time and nothing else. Pagefind indexed the 2,000-page corpus in 6.4 seconds and the 10,000-page corpus in 31 seconds on a GitHub Actions runner; a Lunr build script took 11 and 58 seconds. The index is deployed with the pages, invalidated with the same cache rules, and rolled back with the same rollback.

Hosted search costs money and an integration. Algolia's DocSearch is free for qualifying open-source documentation; commercial plans charge per search request and per record, and a 2,000-page docs site split into section-level records typically holds 15,000–25,000 records. The operational risk is drift: a crawler that runs nightly means search results lag content by up to a day, and a failed crawl can leave results pointing at deleted pages. Pushing records from CI after each deploy solves drift but adds an API key to the pipeline, which must be scoped to write-only access for that index — see Auditing npm Dependencies in SSG Pipelines for secret hygiene in build pipelines.

Multilingual and Multi-Version Content

Two structural questions change the choice. Languages: stemming and tokenisation are language-specific, and an English-stemmed index returns poor results for German compounds or Japanese text with no spaces. Pagefind detects each page's lang attribute and builds a separate index per language automatically; Lunr needs lunr-languages plugins per language, and none of the local tools segment Chinese or Japanese as well as a hosted service. Multilingual Search on Static Sites covers the details.

Versions: a docs site with several versions should not return v2 pages to a reader on v3. Pagefind supports filters (data-pagefind-filter="version:3.2") that are indexed at build time and applied at query time; Algolia uses facets for the same purpose. Whatever the tool, default the filter to the version the reader is currently browsing.

Designing the Search Experience

The index is half the feature. The other half is what the reader sees between typing and clicking, and most of the perceived quality of search is decided there.

Show section context in results. A result titled "Configuration" is useless on a site with forty configuration pages. Display the page's breadcrumb or parent section above the title, and show a highlighted excerpt around the matched term rather than the page description. Pagefind returns an excerpt with <mark> tags and a meta object you can populate with data-pagefind-meta="section:Deployment"; Algolia returns hierarchy levels (lvl0–lvl6) for the same purpose.

Link to the heading, not the page. Long reference pages contain dozens of answers. Pagefind's sub_results and Algolia's section-level records both let a result link to /guide/config/#cache-directory instead of the top of the page, which on the 2,000-page corpus cut the median time from click to answer — measured in moderated sessions — from 14 seconds to 5.

Keyboard first. Documentation readers are developers. Bind / or Ctrl+K to focus search, support arrow keys through results and Enter to open, and restore focus correctly when the dialog closes. Test with a screen reader: the results list needs a live region announcing the count, or blind users hear nothing after typing.

Debounce sensibly. Local tools can query on every keystroke; hosted tools should debounce by 100–150 ms, or a fast typist generates a request per character. On one Algolia-backed site, adding a 120 ms debounce cut billed search requests by 38% with no visible change in responsiveness.

Handle empty results kindly. Suggest the closest matching section, offer a link to the full index or sitemap, and — most importantly — record the query. Zero-result queries are direct evidence of missing or misnamed content.

Measuring Search Quality Over Time

Search quality decays silently as content grows: new pages crowd old answers out of the top three, renamed features stop matching the words readers use, and nobody notices until support tickets rise. Treat search like any other production feature and measure it continuously.

Keep the query test set from the relevance comparison above in the repository as a JSON file of query and expected URL pairs. A small script runs each query against the freshly built index in CI — Pagefind's Node API (pagefind.createIndex, then search) and MiniSearch both run headlessly — and reports the number ranked first and in the top three. Fail the build if either drops by more than two from the stored baseline. On one docs team this caught a template change that accidentally removed data-pagefind-body from API pages, which would have dropped 140 pages out of search entirely.

In production, log three events with a first-party beacon: the query, the rank of the clicked result, and queries with zero results. Reviewed monthly, the zero-result list becomes a writing backlog, and the click-rank distribution tells you whether results are ordered well. A healthy docs search sees more than 70% of clicks on the first result; below 50% means ranking needs work. The collection approach is the same as for web vitals in Building a Core Web Vitals Dashboard from RUM Data.

Privacy, Security and Access Control

A build-time index has a property teams often miss: everything in it is public. The index files sit on the CDN next to the pages, and anyone can download and read them. That is fine for public docs, and a real problem for a site where some pages sit behind authentication. If a password-protected section is indexed into the same Pagefind bundle, its excerpts are readable by anyone who fetches the fragments. Build a separate index for protected content, serve it from behind the same access control as the pages, and exclude protected pages from the public index with data-pagefind-ignore="all". The access-control side is covered in Protecting a Static Site Behind Authentication.

Hosted search has the opposite profile. Queries leave the reader's browser and reach a third party, which matters for privacy policies and for sites serving regulated industries; some teams must disclose it or proxy it. Algolia search-only API keys are designed to be public, but they should be restricted to the specific index and, ideally, to your domain via referrer restrictions. Never ship an admin or write key to the browser — it has happened often enough that secret scanners look for Algolia key patterns specifically.

Finally, both approaches need a Content Security Policy that allows them. Pagefind loads a WebAssembly module, which requires 'wasm-unsafe-eval' in script-src; hosted search needs its API domain in connect-src. Add these deliberately, as described in Writing a Content Security Policy for a Static Site, rather than discovering them from a broken search box after the policy ships.

Generator-Specific Notes

Because Pagefind reads HTML, the generator matters less than for any other feature on a static site. Still, each has a natural integration point:

• Astro / Starlight: Starlight runs Pagefind automatically; plain Astro sites add it with a post-build script or the astro-pagefind integration.
• Hugo: run npx pagefind --site public after hugo --minify; no Hugo changes needed beyond marking the content region. See Indexing Hugo Sites with Pagefind.
• Eleventy: either Pagefind after the build, or a Lunr/MiniSearch index built from the collections API during the build, as in Building a Lunr Index at Build Time in Eleventy.
• Docusaurus: Algolia by default; @easyops-cn/docusaurus-search-local or a Pagefind post-build step for self-contained search.
• Next.js static export: Pagefind over the out/ directory works unchanged.

Common Pitfalls

• Indexing navigation chrome. Without a content boundary, every page's sidebar is indexed, and a query for "installation" matches all pages. Mark the main content region (data-pagefind-body) or exclude chrome.
• Loading search on page load. It adds JavaScript and blocking time to every page for a feature most visitors never use.
• Monolithic indexes on large sites. A multi-megabyte JSON index is a two-to-four-second stall on a phone before the first result.
• Stale hosted indexes. A nightly crawl lags content by a day; push records from CI or accept the lag explicitly.
• Ignoring zero-result queries. They are the best content-gap signal a docs team has. Log them, even with a local search tool, by sending a beacon on queries that return nothing.

Key Takeaways

• Static sites do not need a search server: a build-time index deployed with the pages is always in sync and costs nothing to run.
• Pagefind's fragmented index kept first-query downloads at 64–181 KB from 300 to 10,000 pages, while monolithic indexes grew to several megabytes.
• Hosted search still wins on relevance tuning, analytics and cross-site search; with weighting, Pagefind came within two queries of Algolia on a 60-query test set.
• Load search code only when the reader focuses the search box; eager loading cost 90 ms of Total Blocking Time for no benefit.
• Plan for languages and versions up front: both change how the index is built and filtered.

FAQ

Can a static site have search without a backend?

Yes. Build-time search tools index your content during the build and ship the index as static files. The browser downloads the index, or fragments of it, and runs queries locally. Pagefind, Lunr and MiniSearch all work this way.

Which static search tool scales best?

Pagefind, because it splits the index into small fragments and downloads only those a query needs. On a 10,000-page site the first query downloaded about 180 KB with Pagefind, while a single-file Lunr index was over 9 MB uncompressed.

When is a hosted service like Algolia worth it?

When you need query analytics, synonyms managed by non-engineers, typo tolerance tuned per language, or search across several sites and data sources at once. For a single documentation site, a build-time index is usually enough and costs nothing to run.

Does client-side search hurt Core Web Vitals?

Not if the index loads on demand. Load the search script and index only when the reader focuses the search box, so no search bytes compete with the page's LCP or add main-thread work before the first interaction.

How do I keep search results current?

Build the index in the same build that produces the pages. Because the index is part of the deployed artifact, it can never be out of step with the content, which is a real advantage over crawler-based hosted search.

Related

• Up: Choosing the Right Static Site Generator for Production — search as a framework-selection factor.
• Adding Pagefind to an Astro Site — the full setup with weighting and lazy loading.
• Pagefind vs Algolia DocSearch — the build-time vs hosted decision in depth.
• Building a Lunr Index at Build Time in Eleventy — a monolithic index done well for small sites.
• Search Index Size Budgets for Large Docs — where monolithic indexes stop working.
• Multilingual Search on Static Sites — per-language indexes and stemming.
• Indexing Hugo Sites with Pagefind — search for the generator that ships none.
• Docs Frameworks: Docusaurus, Starlight and VitePress — which search each framework ships by default.