Quick start

Add search to an existing Astro 5 docs site whose content lives in a collection (say src/content/docs) in about five minutes. You’ll get keyword search working first, then add an ANTHROPIC_API_KEY to turn on Claude-powered agentic answers.

Prerequisites

• Astro 5 with at least one content collection.
• A server or hybrid adapter (Node, Cloudflare, Vercel, …) — the /api/ask route renders on demand, so a fully static build can’t serve it.
• An ANTHROPIC_API_KEY to enable agentic search. Keyword search needs no key.

Set up keyword search

1. Install the package Add @hev/ask with your package manager.
2. Register the integration Add hevAsk() to astro.config.mjs and point it at your collection.
3. Add an adapter Install a server/hybrid adapter so /api/ask can render on demand.
4. Drop in the overlay Render SearchOverlay.astro once in your layout and add an opener.
5. Build the knowledge graph Use the Claude Code skill (no key) and commit the JSON.

1. Install

Once published, install from npm:

pnpm add @hev/ask

Until then, consume it straight from the package subdirectory on GitHub:

pnpm add "git+ssh://[email protected]/hev/ask.git#main&path:/packages/ui"

2. Register the integration

// astro.config.mjs
import { defineConfig } from "astro/config";
import hevAsk from "@hev/ask";

export default defineConfig({
  integrations: [
    hevAsk({
      collections: ["docs"],   // your content collection name(s)
      basePath: "/docs/",      // slug → URL prefix: basePath + slug
    }),
  ],
});

collections is the one option you must set; everything else has a default — see the configuration reference.

3. Add a server adapter

The /api/ask route renders on demand. Add whichever adapter matches your host (existing pages stay prerendered — only /api/ask runs as a function); this site uses Cloudflare:

// astro.config.mjs
import cloudflare from "@astrojs/cloudflare";

export default defineConfig({
  adapter: cloudflare({ platformProxy: { enabled: true } }),
  // ...integrations as above
});

4. Render the overlay

Add the component once somewhere global, like your base layout. Any element with data-hev-ask-open opens the palette, and ⌘K is bound automatically.

---
// src/layouts/Base.astro
import SearchOverlay from "@hev/ask/components/SearchOverlay.astro";
---
<button type="button" data-hev-ask-open>
  Search <kbd>⌘K</kbd>
</button>

<slot />

<SearchOverlay />

Keyword search now works. Run astro dev, press ⌘K, and type.

5. Build the knowledge graph

The knowledge graph is an offline-built JSON file you commit. It gives the agentic loop domain context, ranks keyword results, supplies the glossary (so k8s finds kubernetes), and holds the overlay’s suggested questions.

Recommended — the Claude Code skill. In Claude Code, install the bundled skill and ask for it. It builds the graph inside your subscription — no API key, no token spend:

You: build the hev ask knowledge graph

Claude runs:
  ask kg corpus       # emits the sections to distil
  …writes context/glossary/summaries/suggestions…
  ask kg assemble     # writes .hev-ask/kg.json

Or use the CLI — for CI or outside Claude Code, one API call does the same:

export ANTHROPIC_API_KEY=sk-ant-...
pnpm exec ask kg build      # writes .hev-ask/kg.json

Then verify and commit, however you built it:

pnpm exec ask kg verify     # builds the site, checks every anchor resolves
git add .hev-ask/kg.json

Both paths are hash-gated — no model work when content is unchanged — and the integration runs the build automatically during astro build when a key is present. See the CLI reference.

Enable agentic search

Set ANTHROPIC_API_KEY in the server environment where /api/ask runs (your host’s secrets, or .env in local dev). With a key present, pressing Enter in the overlay runs the agentic loop — self-issued sub-queries, a grounded answer, and inline deep links. Without one, Enter returns keyword results.

Verify it works

• Keyword: type a single word from a heading; the top result should deep-link to that section (/docs/page#heading).
• Agentic: type a multi-word question (or click a suggested one) and press Enter; the footer shows the sub-queries the model ran, and a grounded answer streams in with inline deep links.
• Anchors: ask kg verify exits non-zero if any chunk anchor doesn’t exist in the built HTML — wire it into CI.

From here, see the full configuration options or read Concepts to understand what’s happening under the overlay.