Full-text search in docs without paying for an index

Every documentation search you have ever used is one of two designs, and the difference is where the index lives.

A hosted index

A crawler visits your site, sends the content to a service, and the service builds an index on its own machines. Your search box calls their API and shows what comes back. This is what Algolia DocSearch and the search inside most paid docs platforms are.

An index built at publish time

When the site builds, the generator walks every page, extracts the text and headings, and writes a single index file next to the HTML. The search box downloads that file once and answers queries in the reader’s browser. No API, no key, no per-query cost.

Docszero uses the second. The index is built at publish time and served from the site itself, on every plan including Free. There is nothing to sign up for, no crawler to wait on, and no key in your page.

The reflex is that a hosted service must be better because someone charges for it. For a documentation site of ordinary size, most of what you are paying for is capability you will not use.

• It is already correct. The index is generated from the pages in the same build that produced them, so it can never describe a page that no longer exists or miss one published five minutes ago.
• There is no crawl delay. A hosted index is only as fresh as the last crawl. A build-time index is exactly as fresh as the site.
• It works on a private site. A crawler cannot reach password-protected docs, which is precisely where search is most useful.
• No query leaves the reader. What someone searches for in your docs never reaches a third party, which is one less paragraph in your privacy policy.
• It works offline. Export the site, open it from a folder or serve it on an internal network, and search still works, because the index is one of the files.
• It costs nothing per query, so a spike in traffic is not a spike in a bill.

The trade-off is real and it is about size. The index is a file the reader downloads, so it grows with your documentation, and there is a point where downloading it is worse than asking a server.

The numbers depend on how much prose each page carries, so treat them as an order of magnitude rather than a threshold. The shape is what matters: the cost of a built index is paid once per reader and grows with your page count, while the cost of a hosted index is paid per month and grows with your traffic.

The other things you are buying

Size is not the only reason to rent an index. A hosted service typically gives you typo tolerance, synonyms, ranking you can tune, analytics on what people searched for and did not find, and federated search across several sites at once. If any of those is load-bearing for you — particularly the "searched and found nothing" report, which is the best writing prompt in documentation — that is a real reason to pay.

Whichever design you land on, the same handful of things separate search people use from search people give up on.

• It indexes headings as well as body text, and takes you to the heading rather than the top of the page.
• It shows the surrounding sentence, so a reader can tell which result is theirs before clicking.
• It is reachable from the keyboard on every page, not only from the home page.
• It returns something useful for a partial word, because people search while they are still typing.
• It never returns a page that has been unpublished.

The last one is the quiet argument for building the index with the site. A crawler-based index and a deleted page can disagree for hours; an index generated in the same build cannot disagree at all.

Search is built at publish time and served from the site, with nothing to configure. It is on for every site on every plan, and it covers password-protected sites too, because the index is generated rather than crawled.

It travels: Export site includes the index, so a downloaded copy of your docs still searches when you open it from a folder or put it on a machine with no internet. That is the same property that makes the export button meaningful in the first place — a copy of your docs that has lost its search is not really a copy of your docs.