Set up ask the docs yourself

The ask option sets everything up for you. Use the building blocks directly when you need a custom provider, a serverless function instead of an Astro adapter, or the form on a page instead of a button.

Prerequisites

• A Starlight site with Compass and a provider set up.
• A provider with an API key.
• A place to run server code, like an Astro adapter or serverless functions.

Create the endpoint and the form

1. Create an endpoint with createAskHandler():

   src/pages/api/ask.ts

   import type { APIRoute } from "astro";
   import { createAskHandler } from "starlight-compass/handlers";
   
   export const prerender = false;
   
   const handler = createAskHandler({ provider: myProvider });
   
   export const POST: APIRoute = ({ request }) => handler(request);

   The handler takes a Request and returns a Response, so it also works as a serverless function, e.g. a Netlify function.

2. Add the AskDocs component to a page:

   src/content/docs/ask.mdx

   ---
   title: Ask the docs
   ---
   
   import AskDocs from "starlight-compass/components/AskDocs.astro";
   
   <AskDocs endpoint="/api/ask" />

3. Build your site and run astro preview, then ask a question on the page.

Protect the endpoint

The handler has no request limits, unlike the endpoint of the ask option. Every question makes one provider request, so protect it before you publish it:

• Add rate limiting in front of the endpoint, e.g. with your host’s firewall rules.
• Lower maxCandidates and the candidates prop of the component.
• Only allow requests from your own site, e.g. by checking the Origin header.