Documentation
Everything about ondocs, from the first install to the index format. Every page here is also in the index, so you can ask instead.
Start here
- IntroductionWhat ondocs is: open-source Ask AI for your docs, with an MCP server for agents, from one static index. Who it is for, and when it is the wrong tool.
- Getting startedInstall the package, build the index, deploy the endpoint and add the dialog.
- Try it locallyRun the whole pipeline on your machine with mock mode and ondocs dev, no API key.
- TroubleshootingThe messages a new site shows most often, from the package manager, the build, the dialog and the endpoint, what causes each one and how to fix it.
Pick your framework
- Docusaurus
- Astro and Starlight
- VitePress
- Next.js and React
- Fumadocs
- Nextra
- Script tag
- Writing an integration
These docs, live with each plugin: Starlight, Docusaurus and VitePress.
For agents
Deploy & operate
- DeployingWrite the endpoint for Vercel, Netlify, Cloudflare or GitHub Pages with one command, where the index lives, cold starts and cost.
- Workers AI, without an API keyA Cloudflare Worker that answers for any static docs site with Workers AI, the models and their cost, and how large a site fits.
- Rate limits and securityRate limiting, client IPs, CORS, prompt injection and what data leaves your servers.
- Bot check with TurnstileAsk visitors' browsers to pass a Cloudflare Turnstile check before each question, so a fleet of bots cannot spend your model budget.
Guides
- Indexing contentWhat gets indexed, how files become URLs, chunking, excluding pages and the --check mode.
- Model providersBring your own key for OpenAI, Anthropic, Google, xAI, AI Gateway or any AI SDK provider, and configure the embedding model.
- How retrieval worksBM25, cosine similarity, reciprocal rank fusion and the relevance gate that says "I don't know".
- Measure and improve answersScore retrieval in CI with ondocs eval, collect readers' feedback, and keep a log of the questions your docs do not answer.
Reference
- Package APIThe package's imports, the core functions for building and searching an index, and what each entry point exports.
- CLI and config fileEvery flag of ondocs index, init, dev and eval, and the config module for an embedding model the flags don't cover or content that isn't on disk.
- The ask endpointcreateAskHandler options, the request and response, errors and the streaming protocol.
- The ask dialogAskDialog props, the Ask button for your header, the launcher button, shortcuts, theming, accessibility and the useAsk hook.
- The index fileWhat ask-index.json holds, why vectors are int8, and how the file stays small and diffable.
- BenchmarksIndex size, cold start, memory and query latency at 1,000, 10,000 and 50,000 chunks.
- Limits and trade-offsWhere ondocs stops being the right tool, and what it gives up for simplicity.
- FAQShort answers to the questions people ask first, with links to the details.
- Migrating from ask-my-siteask-my-site is now ondocs. What was renamed, what stays, and the commands to move a site over.
- UpgradingThe options each minor version renames, old name to new, and the defaults that change with them.