Pagefind vs Algolia DocSearch

For documentation sites the search decision usually narrows to two options. Algolia DocSearch is the long-standing default: a hosted index, a polished Ctrl+K modal, typo tolerance and analytics, free for qualifying open-source docs. Pagefind is the build-time challenger: an index generated from your HTML, shipped as static files, queried in the reader's browser, and free for everyone. Both are excellent. They fail differently, cost differently and suit different teams.

This comparison runs both on the same 2,000-page documentation site for four weeks — half of readers served each, randomly assigned by a cookie — and measures relevance, latency, freshness and cost. The background on build-time versus hosted search is in Search for Static Sites.

Prerequisites

• A documentation site with stable URLs and heading anchors.
• For DocSearch: acceptance into the DocSearch programme, or an Algolia account with a crawler configured.
• For Pagefind: a post-build step as described in Adding Pagefind to an Astro Site.
• A first-party analytics endpoint if you want comparable click data for both.

How Each Is Set Up

DocSearch has two halves. A crawler, configured with CSS selectors for your page hierarchy (lvl0 for the section, lvl1 for the <h1>, lvl2–lvl6 for subheadings, content for paragraphs), visits the site on a schedule and writes one record per heading section into an Algolia index. The front end loads @docsearch/js, binds the modal to a button and sends each keystroke to Algolia's API.

// DocSearch front end
import docsearch from '@docsearch/js';
docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_ONLY_KEY',   // search-only key, safe to expose
  indexName: 'example_docs',
  searchParameters: { facetFilters: ['version:3.2'] },
});

Pagefind has one half: pagefind --site dist after the build, then a UI loaded on demand. Its "records" are pages with sub-results per heading, and ranking uses the weights you add in markup.

Relevance

A 60-query test set from the site's previous analytics was run against both indexes, and the four-week split test recorded which result position readers clicked.

The gap concentrates in misspellings. DocSearch's typo tolerance matched "deplyoment" and "cahce" correctly; Pagefind returned nothing for both. For correctly spelled queries the two ranked almost identically. Pagefind's gap can be narrowed with a small synonym step: for the ten most common misspellings in your logs, add the misspelled term invisibly to the target page with <span data-pagefind-index-attrs hidden> or via data-pagefind-meta keywords — crude, but it closed three of the seven misses.

Latency and Page Cost

Latency was measured with the Chrome DevTools performance panel on a Moto G Power profile over simulated fast 4G, from keypress to rendered results.

Readers far from Algolia's data centres saw the biggest difference: a test from Johannesburg measured 180–240 ms per keystroke against Algolia's nearest region, while Pagefind stayed local after the first query.

Analytics, Privacy and Control

DocSearch's strongest non-technical advantage is analytics: top queries, queries with no results, click position, all in a dashboard non-engineers can use. Pagefind has none by default, because queries never leave the browser. That is also its strongest privacy argument: no third party receives reader queries, which simplifies privacy notices and removes a processor from your data-protection inventory.

The pragmatic middle ground is a first-party beacon. Send { q, resultCount, clickedRank } to an endpoint you control — a Worker writing to an analytics store is enough, as in Proxying Third-Party APIs from an Edge Function — and you get the three metrics that matter without a vendor. On this site the beacon took 25 lines and produced a zero-result report that led to nine new pages in the following month.

Cost Over a Year

For a site eligible for the DocSearch programme, cost is not a differentiator. For a commercial product's docs, a paid plan at this traffic is a recurring line item that Pagefind replaces with seven seconds of build time.

Migrating Between Them

Switching in either direction is cheaper than teams expect, provided the search component was built as an interface rather than wired directly to one vendor.

Moving from DocSearch to Pagefind takes three steps. Add the Pagefind post-build step and content boundary, and deploy it alongside DocSearch with the new UI hidden behind a query parameter (?search=pagefind) so the team can compare results on production content. Port the ranking intent: DocSearch's lvl0–lvl2 hierarchy maps to Pagefind heading weights and a section meta value, and any facetFilters for versions become data-pagefind-filter attributes. Finally, replace the DocSearch analytics dashboard with a first-party beacon before the switch, not after, so there is a baseline for zero-result rates to compare against. On this site the whole migration took a day and a half.

Moving from Pagefind to DocSearch runs the other way: apply to the programme or configure a crawler, map your heading structure to hierarchy selectors, and verify that the crawler sees the same content boundary Pagefind did. The most common surprise is that the crawler indexes pages Pagefind excluded — tag archives, changelog pages, the 404 page — because exclusion lived in Pagefind attributes the crawler ignores. Add equivalent selectors_exclude rules and a URL exclusion list.

In both directions, keep the reader-facing contract stable: the same keyboard shortcut, the same result layout, the same deep links to headings. Readers notice changes in how search behaves far more than changes in which engine answers, and a stable contract is what makes the split test above possible in the first place.

Pitfalls & Rollback

• Exposing the wrong Algolia key. Only the search-only key belongs in the browser. An admin key in a front-end bundle allows anyone to rewrite your index.
• Crawler selector drift. A template redesign that renames heading classes silently breaks DocSearch's hierarchy; results lose their section labels. Re-test the crawler config after layout changes.
• Pagefind without a content boundary. Navigation text indexed on every page ruins relevance; see the boundary step in the Astro guide.
• Comparing on demo sites. Both are excellent on fifty pages. Test on your own corpus and your own real queries.
• Rollback: the two are front-end swaps behind one search button. Keep the component interface identical — open(), close() — and switching back is a one-line import change and a redeploy.

Conclusion

On a 2,000-page docs site, DocSearch and a tuned Pagefind were within two queries of each other on relevance, with DocSearch ahead on misspellings and analytics and Pagefind ahead on freshness, repeat-query speed, privacy and cost. Teams eligible for the DocSearch programme who value the analytics dashboard should take it. Everyone else should start with Pagefind, add a first-party query beacon, and revisit only if misspelled queries show up as a real problem in the logs.

FAQ

Is Algolia DocSearch free?

DocSearch is free for publicly available technical documentation and open-source projects that qualify for the programme. Other sites use a paid Algolia plan billed on search requests and records, so the cost depends on traffic.

Which gives better search results?

On our 60-query test set, DocSearch ranked the right page first 49 times and a tuned Pagefind setup 47 times. The gap was mostly typo tolerance; for correctly spelled queries the two were nearly identical.

Can Pagefind give me search analytics?

Not by itself, because queries never leave the browser. You can send your own beacon with the query and the clicked result to an endpoint you control, which gives the most useful analytics with a few lines of code.

How quickly do new pages appear in search?

With Pagefind, immediately on deploy, because the index ships in the same artifact. With DocSearch's crawler, on the next crawl, which is typically daily. Pushing records from CI after each deploy closes that gap for Algolia.

Related

• Parent: Search for Static Sites — the full landscape of static search.
• Adding Pagefind to an Astro Site — the tuned Pagefind setup used here.
• Multilingual Search on Static Sites — where hosted search's language handling matters most.
• Docusaurus vs Starlight for Product Documentation — a real migration from DocSearch to Pagefind.
• Self-Hosting Analytics to Cut Third-Party Requests — the first-party beacon approach.