Ask widget

Put an ask box on your docs site

The ask widget is one script and one stylesheet, in vanilla JavaScript with no build step. It sends a question to the query Worker's POST /ask and shows the answer as it streams, with its sources.

Add it to a page

Copy public/ask-widget.js and public/ask-widget.css to your site, from the npm package or from the repository. Then add a target element and the script:

<link rel="stylesheet" href="/ask-widget.css">
<div id="docs-ask"></div>
<script defer src="/ask-widget.js"
        data-endpoint="https://search.example.com/ask"
        data-target="#docs-ask"
        data-label="Ask the docs"
        data-manifest="/corpus-manifest.json"
        data-empty-text="Nothing in the indexed corpus addresses that."
        data-sitekey="YOUR_TURNSTILE_SITEKEY"></script>

The page's origin must be in the query Worker's ALLOWED_ORIGINS, or /ask answers 403.

This website does not embed the widget, so it sends nothing to any search endpoint.

Attributes

Attribute	Default	Use
`data-endpoint`	`/ask`	The URL of the query Worker's `/ask`.
`data-target`	`#docs-ask`	A CSS selector for the element the widget renders into.
`data-label`	`Ask`	The text of the label for the question input.
`data-placeholder`	`Ask a question about the docs`	The input placeholder.
`data-manifest`	none	The URL of a corpus manifest. Without it, sources show as raw object keys.
`data-empty-text`	`Nothing in the indexed corpus addresses that.`	The text shown when a question retrieves no sources.
`data-sitekey`	none	Your Turnstile site key. Set it when the Worker has `TURNSTILE_SECRET`.

What the reader sees

No sources: when a query retrieves no sources, the widget shows data-empty-text, so an answer with no sources does not stay on screen looking authoritative.
An upstream error: the widget shows "Sorry, something went wrong" with a short reason. It does not show the empty-corpus text, because the search did not complete. This is the behavior since v0.6.0.
A bad manifest: a missing or malformed manifest falls back to raw keys. Answers still work.

Turnstile

Turnstile is recommended for a public /ask:

Create a Turnstile widget for your docs domain in the Cloudflare dashboard.
Set the secret on the query Worker: wrangler secret put TURNSTILE_SECRET.
Load the Turnstile script on the pages that embed the ask widget, and set data-sitekey.

Per-site system prompts

One query Worker can serve several sites. ORIGIN_PROFILES is a JSON object in [vars] that maps an exact request Origin to the system prompt for that site:

ORIGIN_PROFILES = '{"https://docs.example.com":"You are the docs assistant...","https://other.example":"You are..."}'

The Worker uses ORIGIN_PROFILES first, then ASSISTANT_SYSTEM_PROMPT. It logs and ignores a malformed value, so a bad var cannot take /ask down.