AI Assistant

Built-in chat assistant that answers questions about your documentation.

Overview

The AI assistant adds a chat dialog to your documentation site. Users can click the sparkle icon in the header to open the dialog and ask questions about the documentation content.

The assistant uses the full documentation text (generated by the llms.txt integration) as context, so it can answer questions about any page on the site.

Enabling the Assistant

Set aiAssistant to true in src/config/settings.ts:

export const settings = {
  aiAssistant: true,
  // ...
};

When enabled:

• A sparkle icon appears in the header bar

• The POST /api/ai-chat endpoint becomes available as a Cloudflare Workers SSR route

Security Warning for Non-Demo Deployments

export const settings = {
  aiChatDemoMode: false,
  // Allow only your deployed docs site to make cross-origin requests.
  aiChatAllowedOrigins: ["https://your-docs-site.example.com"],
  // Cap global daily requests as a cost backstop (false = no ceiling).
  aiChatGlobalDailyLimit: 500,
  // ...
};

Environment Setup

The chat endpoint runs as a Cloudflare Workers SSR route (pages/api/ai-chat.tsx) and reads its configuration from Cloudflare env bindings set in wrangler.toml.

Required CF bindings

Secret — set via wrangler secret put ANTHROPIC_API_KEY:

ANTHROPIC_API_KEY=sk-ant-...

Vars — configure in wrangler.toml:

[vars]
DOCS_SITE_URL = "https://your-docs-site.workers.dev"
RATE_LIMIT_PER_MINUTE = "10"
RATE_LIMIT_PER_DAY = "100"

KV namespace — rate limiting and audit logging:

wrangler kv namespace create RATE_LIMIT

Paste the returned id into the [[kv_namespaces]] block in wrangler.toml.

Uses claude-haiku-4-5-20251001 for fast, low-cost responses.

Chat Dialog

The dialog is a Preact island (src/components/ai-chat-modal.tsx) using the native <dialog> element.

Layout

• Narrow viewports (below lg/1024px): Full viewport width and height

• Wide viewports (1024px and above): Centered, 90vw/90vh with a max width of 52.5rem, with a border

Features

• Balloon-style message bubbles (user on right, assistant on left)

• Markdown rendering in assistant responses (bold, italic, code, lists, links)

• "Thinking..." indicator during API calls

• Error messages displayed inline

• Backdrop click or Escape to close

• Conversation resets on close

MSW Mock (Development Only)

For UI development without a real backend, enable MSW (Mock Service Worker). MSW is dev-only — it never runs in production builds.

Setup:

1. Generate the service worker file (one-time):

   npx msw init public/ --save

2. Set the environment variable:

   .env

   PUBLIC_ENABLE_MOCKS=true

3. Run the dev server (pnpm dev).

The mock handler (src/mocks/handlers.ts) returns a predefined response with a simulated delay. This is useful for styling and testing the chat UI without consuming API credits.

API Reference

For the full endpoint specification (request/response types, error codes, environment variables), see the AI Assistant API reference.

File Structure

src/
├── components/
│   ├── ai-chat-modal.tsx       # Preact island — chat dialog UI
│   └── mock-init.tsx           # MSW initializer (dev only)
├── mocks/
│   ├── handlers.ts             # MSW mock response handlers
│   ├── browser.ts              # MSW browser worker setup
│   ├── server.ts               # MSW node server setup
│   └── init.ts                 # Conditional MSW initialization
├── types/
│   └── ai-chat.ts              # ChatMessage, AiChatRequest/Response types
└── utils/
    └── render-markdown.ts      # Lightweight markdown-to-HTML renderer
pages/
└── api/
    └── ai-chat.tsx             # CF Workers SSR endpoint (prerender = false)