Skip to main content

Getting started

Every setup has the same two halves: an index built with your site, and an endpoint that answers from it. The integration you pick decides how much of that is done for you.

Pick your setup​

  • Starlight or Astro. One plugin or integration in astro.config.mjs, which builds the index and adds the dialog. See Astro and Starlight.
  • Docusaurus. One line in docusaurus.config.ts: the plugin builds the index and adds the dialog. See Docusaurus.
  • VitePress. Wrap the config in .vitepress/config.mts with withOndocs, which builds the index and adds the dialog. See VitePress.
  • Next.js or another React app. Index with the CLI, mount createAskHandler as a route, and render <AskDialog />. See Next.js and React.
  • Fumadocs or Nextra. The same, with the CLI following the framework's URLs. See Fumadocs and Nextra.
  • Any other site. Index the built HTML with the CLI, write the endpoint with npx ondocs init, and add one script tag. See Script tag.

Install​

Install the package with the Vercel AI SDK and a model provider. The two packages the dialog is built on, @radix-ui/react-dialog and cmdk, are optional peer dependencies: leave them out if you only deploy the endpoint.

npm i ondocs ai @ai-sdk/openai @radix-ui/react-dialog cmdk

ondocs is built on AI SDK 7: install ai 7 and its provider packages, such as @ai-sdk/openai 4. A project still on AI SDK 6 has to move to 7 first. ondocs needs Node.js 22.12 or later to build the index. The endpoint itself uses Web APIs only, so it also runs on Bun, Deno and Cloudflare Workers.

Build the index​

Point the CLI at your content. It reads Markdown, MDX and HTML, splits pages at every heading, embeds the chunks and writes ask-index.json:

npx ondocs index ./docs --base-url /docs \
  -e openai:text-embedding-3-small --dimensions 512

With the Docusaurus, Astro, Starlight or VitePress plugin you skip this step: the plugin indexes the built site after every build.

Add the endpoint​

The endpoint is one function. It takes a Web Request and returns a streaming Response, and it must embed questions with the same model the index was built with:

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'),
  // The index's model, at the index's 512 dimensions.
  embeddingModel: openai.embedding('text-embedding-3-small'),
});

npx ondocs init writes this for your host, with a rate limit and a daily budget: Vercel, Netlify, Cloudflare, or a Cloudflare Worker with Workers AI and no API key for a site on GitHub Pages. An Astro site with an SSR adapter needs nothing: the integration serves it. See Deploying.

Add the dialog​

In a React app, render the dialog once near the root and import its two stylesheets:

import { AskDialog } from 'ondocs/react';
import 'ondocs/react/styles.css';
import 'ondocs/embed/launcher.css';

<AskDialog launcher suggestions={['How do I install it?']} />;

launcher adds a floating "Ask AI" button. The dialog also opens with ⌘I on macOS and Ctrl+I elsewhere, so ⌘K stays with your site's search. The plugins and the script tag add the same dialog for you, with the same shortcut.

Try it without an API key​

Mock mode runs the whole pipeline offline: a deterministic embedding model and a scripted model that answers by quoting the best-matching sentences, with citations. Build with -e mock and serve the endpoint locally with npx ondocs dev. Try it locally walks through it.

When something fails​

Troubleshooting lists the messages a new site shows most often, from a package manager that installs an older version to a dialog that cannot answer, with the cause and the fix of each.