Astro Docs AI: Starlight Integration

Adding an AI agent to an Astro Starlight documentation site lets readers get answers from your own docs with citations — and Astro's script handling makes the injection clean and build-safe. If you've built docs on Starlight, the setup takes minutes.

Why Starlight docs are a great fit

Starlight is Astro's documentation framework, built for fast, accessible docs — exactly the content an AI agent answers well. Readers want the answer, not a search page. An agent reads your docs and responds directly, citing the page. Starlight's clean structure and headings retrieve cleanly. See the documentation use case.

Step 1: Index your content

Create an account, get your publishable site key, and point the platform at your built Starlight site to crawl, or connect the repository. The platform chunks and embeds your content for retrieval at answer time. Schedule a re-crawl so each release keeps the agent current.

Step 2: Inject the widget the Astro way

Astro and Starlight give you supported ways to add scripts — through the site's head configuration or a small client script that loads on every page. Register the AIML.chat embed there with your publishable key so it loads reliably across the built site rather than being stripped. Because it's async, it doesn't affect your docs' performance. Keep the key in an environment variable.

Step 3: Configure a technical agent

Choose a technical agent for precise, cited answers that include the relevant snippet. Give it a grounded prompt: answer only from your indexed docs, cite sources, and escalate when the answer isn't there. Grounding keeps it from inventing an option that doesn't exist — see what is RAG.

Step 4: Structure for retrieval

Retrieval rewards clean docs. Keep pages focused, use clear headings, lead with the answer, and write descriptive titles. Split any page too long to chunk well. These habits improve the agent's answers and help readers navigate.

Step 5: Close the gaps

After launch, the analytics show what readers ask and which questions the agent couldn't answer — a precise docs backlog. Write those pages, re-crawl, and the agent improves. Support questions become a roadmap.

What you get

Your Starlight docs now answer questions directly, with cited responses, around the clock, in the reader's language. Developers get unblocked without a ticket, and you see where your documentation is thin. See how to add AI agents to Docusaurus for a framework comparison.

Why grounding beats a generic widget

Whatever platform you are on, the value is not the chat box — it is that the answers come from your own content. A generic chatbot bolted onto Starlight will improvise from a general model and confidently get your details wrong, which erodes trust fast. A grounded agent answers only from what you indexed and cites the page, so every reply is traceable to something you actually published. That is the difference between a widget that frustrates visitors and one they come to rely on, and it is why indexing your real content is the step that matters most.

Getting started

Add an agent to your Starlight docs on the AIML.chat free plan: index your content, inject the embed via the head config, and configure the agent. Compare tiers on the pricing page.