Replace Your Docs Site Search With AI Answers (Mintlify, Docusaurus, GitBook)
Keyword search misses most real questions. Here is how to replace your docs site search with search plus cited AI answers on Mintlify and Docusaurus, what works on GitBook, and how to tell if it helped.
Most docs sites ship with keyword search: the box in the top bar, opened with Cmd+K, that matches the words you type against an index of pages. It's fast, and for a reader who knows the exact name of what they want, it works. For everyone else it often comes back empty, or with ten links and no answer.
This guide covers why keyword search misses questions, how to replace your docs site search with AI search that can also answer, how to set it up on Mintlify, Docusaurus and GitBook, and how to tell whether it worked.
Why does keyword search miss questions?
Keyword search matches the words in the query against the words on the page. That breaks in predictable ways:
- Different words. A reader types "rotate my key". Your page says "regenerate API credentials". No words in common, so nothing is found.
- Questions, not keywords. "Why does my webhook return 401 after I changed regions?" is a full sentence. A keyword engine weighs every word, including the ones that don't matter.
- The answer spans pages. Setting up SSO might touch a guide, a settings reference and a troubleshooting page. Search returns three links and leaves the reader to stitch them together.
- Results aren't answers. Even a perfect hit is a page to read. The reader still has to find the two sentences that apply to them.
How does "replace site search" work?
Kelu's website widget can take over your docs site's search. The setting shipped in Kelu 1.8.0 as Replace site search. Behind it is retrieval built for questions. Pure semantic search fixes the different-words problem but can miss exact strings, such as error codes and parameter names, that keyword search handles well. So Kelu runs hybrid search, vector search for meaning and full-text search for exact terms, fuses the results by rank, then uses a reranker that reads the question and each candidate passage together.
The result is search that can also answer. A reader looking for a page gets results fast, and no answer is generated for a plain lookup. A reader with a real question is one click from a cited answer. When your docs don't cover the question, the answer says so and shows no citations, instead of guessing.
The chat also shows matching pages while the reader types, after two characters and a short pause. Search and chat run on the same knowledge base, so the pages a reader finds are the pages an answer cites. The widget has other layouts too: a floating chat, a docked sidebar, and a search view that opens near the top of the screen like a command palette. See the website widget for all of them.
With Replace site search on, this is what changes:
- Your site's search box opens Kelu's panel on the Search tab instead of your old search dialog. On Mintlify the widget finds the search box by itself. On other sites you name it with a CSS selector.
- Cmd+K (Ctrl+K on Windows and Linux) opens the Search tab too, and your site's own Cmd+K search no longer opens.
- The Search tab lists up to 8 matching pages, each with its title, section path and a snippet. Enter runs the search, and arrow keys move through the results.
- An "Ask AI: …" row sits above the results. One click sends the same query to the chat, which writes an answer with numbered citations.
How do you set it up on Mintlify, Docusaurus and GitBook?
First, check what your platform already offers. Algolia DocSearch, the free search used by many open-source docs sites, now has an Ask AI mode next to keyword search. Mintlify includes an AI assistant on its Pro and Enterprise plans, and GitBook includes AI answers on its paid site plans. If one of those fits, use it. The case for a separate assistant is one knowledge base across your docs, help center, tickets and repos, answering the same way on your site, in your helpdesk, in Slack and in AI coding tools. For a side-by-side of docs assistants, see RAG platforms for docs.
Start the same way on every platform. Create a knowledge base, add your docs as a website source, and let the first crawl finish. Kelu creates a widget for you with the knowledge base. Check that your docs domain is on the widget's Sites it works on list on its Install tab (Kelu fills it in from your first website source), then follow your platform below.
Mintlify. Mintlify runs every .js file in your docs folder on every page, on every plan including the free Starter. Add a file named kelu-widget.js in the folder that holds docs.json, paste the loader from the widget's Install tab, and push. Then turn on Replace Mintlify's search on the widget's Search & opening tab. The file doesn't need to change. Mintlify's search box, the search icon on phones and Cmd+K now open Kelu's Search tab, and Mintlify's own search dialog no longer opens. On Mintlify Pro and Enterprise you can also make the assistant button in the top bar open Kelu's chat. See the Mintlify integration.
Docusaurus. Add the widget to the scripts option in docusaurus.config.js, with the widget id and client key from the Install tab. To replace Algolia DocSearch, add two attributes to the same entry: data-replace-site-search set to "true", and data-modal-override-open-selector-search set to your search button's CSS selector. On a Docusaurus site that uses DocSearch, the button has the class DocSearch-Button, so the selector is .DocSearch-Button. Rebuild and deploy. Your search button and Cmd+K then open Kelu's Search tab, and DocSearch's dialog doesn't open behind it. To keep DocSearch and add AI answers beside it instead, leave those two attributes out and turn off Open with Cmd/Ctrl+K on the widget, so only one thing opens on the shortcut. See the Docusaurus integration.
GitBook. GitBook doesn't let you add your own code to a site it hosts: its documentation says custom CSS, HTML and JavaScript can't be inserted into a GitBook site. So Kelu can't replace search on GitBook-hosted pages. You can still index your GitBook site as a website source and answer from it elsewhere: put the widget on your own site or app, answer in Slack or Teams, or let AI coding tools query it through the MCP server. If your docs domain runs through a proxy you control, such as a Cloudflare Worker, the proxy can add the widget to every page. That doesn't work for gitbook.io addresses. See the GitBook integration.
Other platforms follow the same pattern: add the script with data-replace-site-search="true" and data-modal-override-open-selector-search set to your search box's CSS selector. Kelu's docs have guides for ReadMe, VitePress, MkDocs, Sphinx, Astro Starlight and plain HTML.
How do you measure it: gaps and feedback?
Replacing search is only worth it if readers find answers more often. A simple before and after works: note your ticket volume on documented topics for a month, switch, then compare. Expect the first weeks to surface gaps rather than close them. That is the point. Each gap you fill raises the share of questions your docs answer, on the widget and on every other surface that uses the same knowledge base.
These are the places that tell you how it's going:
- Coverage Gaps. Questions the assistant said it could not answer, grouped by topic, for a week, month or quarter. Each topic has a finding, a suggestion for what to write, and the nearest existing pages. Your old search box could at best report zero-result queries. This report keeps the whole question. See knowledge gaps.
- Feedback and citation coverage. Analytics shows thumbs up and down from the widget, the API and the Slack and Teams bots, the share of answers that cited a source, and a self-serve rate split by intent. Read the thumbs-down answers first. A cited answer rated down usually means a page exists but doesn't answer the question.
- Search events. The widget fires onSearchResultsCompleted when results are shown, onSearchResultClick when a reader opens a result (with its rank), and onModeSwitch when they move between Ask AI and Search. Send them to your own analytics to see whether readers click results or ask.
- Traces. Each answer is recorded with its query, sources, latency and token counts, and each search with its query, results and latency, so a bad result can be traced to the page behind it.
FAQ
Does every search write an AI answer? No. The Search tab lists matching pages and writes no answer. A reader who wants one clicks the "Ask AI" row or switches to the Ask AI tab.
Can I replace Algolia DocSearch on Docusaurus? Yes. Add data-replace-site-search="true" to the widget's script entry and point data-modal-override-open-selector-search at .DocSearch-Button. The search button and Cmd+K then open Kelu's Search tab instead of DocSearch's dialog. Remove the attribute to go back.
Does it work on Mintlify without code changes? After the one-time loader file, yes. Replace Mintlify's search is a switch on the widget's Search & opening tab, and the widget finds Mintlify's search box by itself.
Can I use it on GitBook? Not on pages GitBook hosts, because GitBook doesn't allow custom scripts there. Index the GitBook site as a website source and answer on your own site, in Slack or Teams, or through MCP. A proxy you control on a custom domain can also add the widget.
What happens when the docs don't cover a question? The answer says it doesn't know and shows no citations. The question then shows up in Coverage Gaps, so you can write the missing page.
Keep reading
GEO for Documentation: Getting Your Docs Cited by AI Answers
Generative engine optimization is SEO's successor problem: your docs now need to win citations inside AI answers, not just rankings on a results page.
Knowledge Gap Analysis: Turning Unanswered Questions into a Docs Roadmap
A knowledge gap is a real question your content cannot answer. Captured systematically, gaps replace gut-feel docs planning with a ranked, evidence-based backlog.
What Is Ticket Deflection? Definition, Formula, and How to Improve It
Ticket deflection is the share of support questions resolved without creating a ticket. Here is how to define it, measure it honestly, and raise it.
Turn your knowledge into answers
Connect your docs, policies, or playbooks and see cited AI answers in minutes — free, no credit card required.
Free to start · No credit card required