OneTag AI / Guides

Add 'ask the docs' AI search to a documentation site

How do I add AI question answering to a static documentation site (VitePress, Docusaurus, MkDocs, Starlight)?

Readers of documentation ask questions, not keywords: "does this work with Next.js 15", "how do I rotate the key". Hosted answers products (kapa.ai, Inkeep, Algolia Ask AI) do this well and charge for it. A static site can do most of it itself: a search index built at deploy time finds the relevant sections, and one model call turns them into an answer.

This guide shows the pattern with Pagefind, which already ships with Starlight and works with any static output. The same idea applies to VitePress, Docusaurus and MkDocs: build an index, retrieve, then ask.

Steps

1. Get a free key

   From onetagai.com.

2. Index the site at build time

   Pagefind indexes the built HTML: npx pagefind --site dist. Starlight does this already. For VitePress, Docusaurus or MkDocs, add the command after the build.

3. Retrieve, then ask

   On the search page:

   <script src="https://onetagai.com/v1.js" data-key="YOUR_ONETAG_KEY"></script>
   <script type="module">
     const pagefind = await import("/pagefind/pagefind.js");
     async function askDocs(question) {
       const results = await pagefind.search(question);
       const top = await Promise.all(results.results.slice(0, 5).map((r) => r.data()));
       const context = top.map((d) => `# ${d.meta.title}\n${d.excerpt}\n${d.url}`).join("\n\n");
       return onetag.ask(question, context, {
         system: "Answer from the documentation excerpts only. Cite the page URL you used. If the answer is not there, say so.",
       });
     }
     // askDocs("How do I rotate the key?")
   </script>

4. Show the answer with its sources

   Render the answer and link the URLs the model cites. Readers trust an answer that points at the page it came from, and the link is the fallback when the answer is wrong.

Why retrieve first

One onetag.ask call takes up to 32,000 characters. A documentation site is far larger, and sending everything would be slow and expensive even if it fit. Retrieval picks the five sections that matter, which also makes the answer more accurate: the model sees only relevant text.

Full page text instead of excerpts

Pagefind's excerpt is a short snippet. For better answers, index the full text: set data-pagefind-meta="text:…" or build your own JSON index at build time ({url, title, text} per section) and use MiniSearch in the browser. The astro-onetag integration does this for Starlight; it is listed on the templates page.

Prompt that behaves

Tell the model to answer only from the excerpts, to cite the URL, and to say when the docs do not cover the question. That last instruction removes most hallucinated answers. Keep maxTokens around 400 for a docs answer.

Cost

Five excerpts plus a question is about 1,500 tokens; the answer about 300. A free key covers roughly 500 questions; Pro covers about 50,000 a month.

Questions

Related guides

• Add AI to an Astro site
• Ways to add AI to a static site, compared
• Add a TL;DR summary button to blog posts
• Is it safe to put an AI API key in a static HTML page?

Updated 2026-11-09. Something wrong or missing? Email support@odysseyx.app.