Open source · MIT
Open-source Ask AI for your docs.
Cited answers on your own model key, and an MCP server for coding agents, from one index built with your Starlight, Docusaurus or VitePress site. No vendor, no vector database.
Add it to
import ondocs from 'ondocs/starlight';
starlight({ title: 'Acme Docs', plugins: [ondocs()] });export default {
plugins: ['ondocs/docusaurus'],
};import { defineConfig } from 'vitepress';
import { withOndocs } from 'ondocs/vitepress';
export default withOndocs(defineConfig({ title: 'Acme Docs' }));import { createAskHandler } from 'ondocs/server';
export const POST = createAskHandler({ index, model });This site is built this way.Next.js guide
<script src="https://cdn.jsdelivr.net/npm/ondocs@0.18/dist/embed.global.js"
data-endpoint="/api/ask" defer></script>Ask these docs
Question: How do I add it to Docusaurus?
Put the plugin in the plugins array of docusaurus.config.ts:
// docusaurus.config.ts
export default {
// …
plugins: ['ondocs/docusaurus'],
};
``` [2]Sources
5 more sources, not cited
- Docusaurus/docs/docusaurus
- Docusaurus › The dialog and the shortcut/docs/docusaurus#the-dialog-and-the-shortcut
- Writing an integration/docs/writing-an-integration
- Docusaurus › Locales and versions/docs/docusaurus#locales-and-versions
- Writing an integration › Add the launcher/docs/writing-an-integration#add-the-launcher
For coding agents:
https://ondocs.vercel.app/api/mcp
Live demos
These docs, on real Starlight, Docusaurus and VitePress sites.
Each site is built with its framework’s plugin, and its Ask dialog answers from this site’s endpoint. Open one and ask it something.
Set up
One line for Starlight, Docusaurus and VitePress. A script tag for everything else.
Every setup has the same two halves: an index built with your site, and one function that answers from it. The plugins do the first half for you.
A Starlight plugin, and an integration for any other Astro site. It indexes what Starlight’s own search indexes into dist/ask-index.json, and adds the dialog to every page.
Install
Shellnpm i ondocs ai @ai-sdk/openaiAdd the plugin
JavaScript// astro.config.mjs import starlight from '@astrojs/starlight'; import ondocs from 'ondocs/starlight'; import { defineConfig } from 'astro/config'; export default defineConfig({ integrations: [starlight({ title: 'Acme Docs', plugins: [ondocs()] })], });Deploy as you do now
With an SSR adapter, the integration serves the ask and MCP endpoints itself: there is no file to write. A static site writes its endpoint with
npx ondocs init. Astro with an adapter
A Docusaurus 3 plugin. After every build it indexes the pages your site serves into build/ask-index.json, and it adds the dialog behind a floating “Ask AI” button and ⌘I.
Install
Shellnpm i ondocs ai @ai-sdk/openai @radix-ui/react-dialog cmdkAdd the plugin
TypeScript// docusaurus.config.ts export default { plugins: ['ondocs/docusaurus'], };Write the endpoint
One function on your host answers from the index, with your model key, rate-limited and on a daily budget.
npx ondocs initwrites it for Vercel, Netlify, Cloudflare, or GitHub Pages with Workers AI and no API key, and deploys nothing. What it writes for each hostShellnpx ondocs init
A VitePress plugin that wraps your config. After every build it indexes the pages your site serves into .vitepress/dist/ask-index.json, and it adds the dialog behind a floating “Ask AI” button and ⌘I.
Install
Shellnpm i ondocs ai @ai-sdk/openaiWrap the config
TypeScript// .vitepress/config.mts import { defineConfig } from 'vitepress'; import { withOndocs } from 'ondocs/vitepress'; export default withOndocs( defineConfig({ title: 'Acme Docs', }), );Write the endpoint
One function on your host answers from the index, with your model key, rate-limited and on a daily budget.
npx ondocs initwrites it for Vercel, Netlify, Cloudflare, or GitHub Pages with Workers AI and no API key, and deploys nothing. What it writes for each hostShellnpx ondocs init
Index your content with the CLI, mount the handler as a route, and render the dialog. This site is built exactly this way.
Index your content
Shellnpx ondocs index content --base-url /docs -e openai:text-embedding-3-smallMount the endpoint
TypeScript// app/api/ask/route.ts import { openai } from '@ai-sdk/openai'; import { createAskHandler } from 'ondocs/server'; import index from '../../../ask-index.json'; export const POST = createAskHandler({ index, model: openai('gpt-5.4-mini'), embeddingModel: openai.embedding('text-embedding-3-small'), });Render the dialog
TSX'use client'; import { AskDialog } from 'ondocs/react'; import 'ondocs/react/styles.css'; import 'ondocs/embed/launcher.css'; export const Ask = () => <AskDialog launcher />;
Hugo, Jekyll, Eleventy, MkDocs or plain HTML: index the HTML your generator built, write the endpoint with one command, and add one script tag. The dialog loads the first time it is wanted.
Index the built site
Shellnpx ondocs index public -e openai:text-embedding-3-smallWrite the endpoint
One function on your host answers from the index, with your model key, rate-limited and on a daily budget.
npx ondocs initwrites it for Vercel, Netlify, Cloudflare, or GitHub Pages with Workers AI and no API key, and deploys nothing. What it writes for each hostShellnpx ondocs initAdd the script tag
HTML<script src="https://cdn.jsdelivr.net/npm/ondocs@0.18/dist/embed.global.js" data-endpoint="/api/ask" defer ></script>
For agents
The same index, for the agents that read your docs.
Coding agents and AI apps search and read your docs over MCP, with their own model. Search is keyword-only by default, so it calls no model at all. Connect yours to these docs:
These docs are an MCP server at https://ondocs.vercel.app/api/mcp. Connect your AI tool to it, and its agent can search and read them.
Add to CursorAdd to VS CodeAdd to Claude
Claude Code:
claude mcp add --transport http ondocs https://ondocs.vercel.app/api/mcpCodex:
codex mcp add ondocs --url https://ondocs.vercel.app/api/mcpGemini CLI:
gemini mcp add --transport http --scope user ondocs https://ondocs.vercel.app/api/mcpChatGPT: add a custom MCP server with this URL at chatgpt.com/plugins.
Other clients
{
"mcpServers": {
"ondocs": {
"type": "http",
"url": "https://ondocs.vercel.app/api/mcp"
}
}
}Codex, in ~/.codex/config.toml:
[mcp_servers.ondocs]
url = "https://ondocs.vercel.app/api/mcp"{
"results": [
{
"id": "/docs/workers-ai",
"title": "Workers AI, without an API key",
"heading": "",
"url": "https://ondocs.vercel.app/docs/workers-ai",
"text": "A docs site on GitHub Pages, S3, Read the Docs or any other host that only serves files can have its Ask box and its MCP endpoint answered by a Cloudflare Worker with Workers AI, Cloudflare's own models.…"
}
]
}search and fetch
Ranked sections with a snippet and a link to the anchor, then the page or section as Markdown: the shape ChatGPT’s connectors expect, over MCP 2026-07-28 and 2025-11-25.
llms.txt and .md pages
The plugins also write llms.txt, llms-full.txt and a Markdown copy of every page, and leave alone what another llms plugin writes.
Add to Cursor, VS Code, Claude
With the plugins’ mcp option, a docs page shows the install links and the Claude Code command for your endpoint.
How it works
Indexed when you deploy. Searched in memory when someone asks.
Docs change when you deploy, not between requests, so the index is a file built with the site instead of a database kept in sync with it.
Build time once per deploy
ondocs indexReads your Markdown, MDX or built HTML. Splits it at every heading, embeds each chunk and quantizes the vectors to int8.ask-index.json1.6 MB per 1,000 chunks, deployed with the site.Rebuilt on every deploy, re-embedding only the chunks whose text changed. --check fails CI when a committed index is stale.
Request time per question
Keywords and meaning
BM25 finds exact names like createAskHandler and error codes; vectors find paraphrases. Reciprocal rank fusion merges the two rankings by rank alone.
A gate before the model
Most off-topic questions get “I don’t know” before the model is called, fast and free. One that shares enough words with your docs can still reach it, and the model is told to answer from the sources alone.
Citations that land
Pages are split at every heading, so 1 opens the section an answer came from, at the URL your framework serves.
Numbers
Measured, at the sizes a docs site has.
- 1.6 MBindex for 1,000 chunks
- int8 vectors in base64; 0.9 MB gzipped. The same index as float JSON is 7.5 MB.
- 0.71 msmedian query over 1,000 chunks
- BM25, cosine scan and fusion, in memory. 6.96 ms at 10,000 chunks.
- 3.6 KBscript tag on each page, gzipped
- The button and shortcut. The dialog loads the first time it is wanted.
- 22 / 22agent-style searches we wrote, with the right page in the top three
- On docusaurus.io’s own docs, keyword-only: no model call. Checked in CI. The queries
- 20 / 22the same needs, asked as a person asks
- Questions we wrote too. Real Stack Overflow and GitHub questions, in their own words, find the right page far less often.
- ≤ 800output tokens per answer, by default
- With at most 8,000 characters of sources in: one embedding call and one model call.
From pnpm bench on an Apple M1 Max with Node 24.18: synthetic, documentation-shaped corpora with 512-dimension vectors, 1,000 queries per size. Query times exclude the embedding API call. All results
Compared
A local index like Pagefind’s, plus cited answers. No cloud account.
| Hosted assistantsKapa, Inkeep, Algolia Ask AI, Biel.ai | ondocsA library, on your infrastructure | Search onlyPagefind, Orama’s local index | |
|---|---|---|---|
| What a visitor gets | Written answers with citations | Written answers citing the exact section | A list of matching pages |
| Where your docs are indexed | On the vendor’s platform | A static file in your build | Static files in your build |
| What you run | Nothing, it is hosted | One function: Vercel, Netlify, Cloudflare or any Request → Response runtime | Nothing |
| Model and key | The vendor’s (Algolia Ask AI: yours) | Yours, through any AI SDK provider | None |
| Account and pricing | A vendor account and plan | None. You pay your model provider per question | None |
| For agents | Hosted MCP on most plans | Your own MCP endpoint and llms.txt; by default, agent search calls no model | No |
| Follow-up questions and dashboards | Typically included | Follow-ups, yes. No dashboard: log questions with onFinish | No |
When it’s the wrong tool
- Past about 50,000 chunks. Search is an exact scan; at that size an approximate index or a vector database is better.
- Content that changes per user or per request. The index is rebuilt when you deploy.
- Multi-turn chat with a dashboard, and nothing to run. A hosted assistant does that.
- Search results with no server at all. Use Pagefind.
Add it to your docs.
Try it on your own content in two minutes, without an API key: index with the mock model and run npx ondocs dev.
$ npm i ondocs
$ npx ondocs index ./docs -e mock
$ npx ondocs dev