AI Chat

Add a documentation-aware AI chat with a server-only provider key and framework endpoint.

AI Chat answers questions using the pages in your Heyo Docs site. Configure a provider in heyo-docs.config.ts, then add the server endpoint for your framework. The browser sends chat messages to that endpoint; the provider key stays on the server.

Configure the chat

Add ai.chat to the site configuration. Heyo Docs supports OpenAI, Anthropic, and xAI through the openai, claude, and grok providers.

heyo-docs.config.ts

export default heyoDocs({
  content: "content",
  ai: {
    chat: {
      provider: "openai",
      key: process.env.OPENAI_API_KEY!,
      model: "gpt-5-mini",
      variant: "right",
      icon: "chat",
      text: "AI Chat",
      name: "Docs Assistant",
      placeholder: "Ask AI about the docs",
    },
  },
});

Inside ai.chat, only provider, key, and model are required.

Setting	Default	Purpose
`provider`	Required	`openai`, `claude`, or `grok`.
`key`	Required	Server-only API key for the selected provider.
`model`	Required	Provider model identifier, such as `gpt-5-mini`.
`variant`	`right`	`right` shows a trigger; `center` shows a compact prompt at the bottom.
`icon`	`chat`	Icon in the `right` trigger.
`text`	`AI Chat`	Label in the `right` trigger.
`name`	`AI`	Drawer title and assistant message label.
`placeholder`	`Ask AI about the docs`	Text in both the `center` prompt and drawer composer.

With variant: "center", submitting the compact prompt opens the drawer. With variant: "right", the reader opens the drawer from its floating trigger. The drawer remains available while readers move between pages.

Add the chat endpoint

The chat UI sends POST requests to /heyo-docs-internal/ai-chat. Add this endpoint before enabling ai.chat; createAiChatResponse supplies the model with the loaded documentation pages and streams its answer back to the UI.

React Router

Add this entry to the existing route array:

app/routes.ts

import { route, type RouteConfig } from "@react-router/dev/routes";

export default [
  // Existing routes…
  route("heyo-docs-internal/ai-chat", "routes/ai-chat.ts"),
] satisfies RouteConfig;

Then create app/routes/ai-chat.ts:

app/routes/ai-chat.ts

import { createAiChatResponse } from "@heyo-sh/heyo-docs/ai";
import type { ActionFunctionArgs } from "react-router";

import config from "../../heyo-docs.config";
import { pages } from "virtual:heyo-docs-content";
import { pages as markdownPages } from "virtual:heyo-docs-content/server";

export async function action({ request }: ActionFunctionArgs) {
  if (request.method !== "POST")
    return new Response("Method Not Allowed", {
      headers: { Allow: "POST" },
      status: 405,
    });

  return createAiChatResponse(request, {
    ai: config.ai,
    markdownPages,
    pages,
    title: config.title,
  });
}

Astro

Create src/pages/heyo-docs-internal/ai-chat.ts:

src/pages/heyo-docs-internal/ai-chat.ts

import { createAiChatResponse } from "@heyo-sh/heyo-docs/ai";
import type { APIRoute } from "astro";

import config from "../../../heyo-docs.config";
import { pages as markdownPages } from "virtual:heyo-docs-content/server";

export const prerender = false;

export const POST: APIRoute = ({ request }) =>
  createAiChatResponse(request, {
    ai: config.ai,
    markdownPages,
    pages: markdownPages.map((page) => ({
      description: page.description,
      searchContent: page.raw,
      slug: page.slug,
      title: page.title,
    })),
    title: config.title,
  });

Next.js

Create app/heyo-docs-internal/ai-chat/route.ts:

app/heyo-docs-internal/ai-chat/route.ts

import { createAiChatResponse } from "@heyo-sh/heyo-docs/ai";

import config from "../../../heyo-docs.config";
import { docsPages, markdownPages } from "../../_heyo-docs/server";

export const runtime = "nodejs";

export async function POST(request: Request) {
  return createAiChatResponse(request, {
    ai: config.ai,
    markdownPages,
    pages: docsPages,
    title: config.title,
  });
}

Keep the key server-only

Use a server environment variable for key; do not put it in client code or commit it to the repository. Heyo Docs replaces the browser-side value with an empty string; the server endpoint retains the key needed to call the provider.