Docs — Spotlight

Quick Start

Spotlight is a single JavaScript file. Add one <script> tag to your HTML and your visitors get Cmd+K search instantly — no build step, no package install, no API keys needed.

Step 1 — Create a project

Sign up at spotlight.cx, enter your website URL, and click Start Indexing. Spotlight automatically crawls up to 30 pages, reads the content, and builds a searchable model of your site in about 2 minutes.

Step 2 — Copy your project ID

Once indexing is complete, you'll see a project ID like proj_a1b2c3d4 in your dashboard.

Step 3 — Add the script tag

Paste this before the closing </body> tag on your site:

<script
  src="https://cdn.spotlight.cx/widget.iife.js"
  data-project="YOUR_PROJECT_ID"
></script>

That's it. Your visitors can now press ⌘K (Mac) or Ctrl+K (Windows/Linux) to open Spotlight.

Installation

Spotlight works on any website — static HTML, WordPress, Webflow, Squarespace, Next.js, Rails, or anything that lets you add a script tag.

Static HTML

Add the script tag to your <head> or before </body>. Using defer is supported.

<script
  src="https://cdn.spotlight.cx/widget.iife.js"
  data-project="YOUR_PROJECT_ID"
  defer
></script>

WordPress

Add the script tag to your theme's footer.php before </body>, or use a plugin like Insert Headers and Footers.

Webflow

Go to Project Settings → Custom Code → Footer Code and paste the script tag there.

Next.js / React

Use Next.js's <Script> component in your root layout:

import Script from 'next/script'

<Script
  src="https://cdn.spotlight.cx/widget.iife.js"
  data-project="YOUR_PROJECT_ID"
  strategy="afterInteractive"
/>

Configuration

Spotlight is configured entirely via data-* attributes on the script tag. No JavaScript required.

Attribute	Default	Description
data-project	—	Required. Your project ID from the dashboard.
data-color	#6366f1	Accent color for the widget (hex or RGB).
data-position	bottom-right	Position of the trigger button: bottom-right, bottom-left, top-right, top-left.
data-placeholder	Search…	Placeholder text in the search input.
data-shortcut	cmd+k	Keyboard shortcut to open the widget. Use ctrl+k for Windows default.
data-hide-badge	false	Set to true to hide the 'Powered by Spotlight' badge (Pro plan only).
data-theme	light	Widget theme: light or dark.

Example with all options

<script
  src="https://cdn.spotlight.cx/widget.iife.js"
  data-project="proj_a1b2c3d4"
  data-color="#0ea5e9"
  data-position="bottom-right"
  data-placeholder="Search documentation…"
  data-shortcut="cmd+k"
  data-hide-badge="true"
  data-theme="light"
></script>

How Search Works

Spotlight uses a two-layer search model: semantic vector search for natural language queries, and keyword matching as a fallback for exact terms.

Indexing

When you create a project, Spotlight's crawler visits your site (up to 30 pages on Free, 100 on Pro). For each page it reads the visible text content, extracts semantic chunks, and generates vector embeddings. These embeddings are stored in our infrastructure and downloaded to the visitor's browser on first use.

In-browser search

After the first visit, all search runs locally in the browser using the downloaded index. This means zero server round-trips per query — search results are instant even on slow connections.

Ask AI fallback

When the user clicks Ask AI, the query is sent to our API along with the top relevant chunks from the index. Our LLM synthesizes a direct answer from your site's own content. The answer is grounded — it never makes up information that isn't on your site.

Re-indexing

You can manually trigger a re-index from the dashboard whenever you update your site. Auto re-index (daily or on-deploy webhook) is available on the Pro plan.

FAQ

Does Spotlight work with password-protected pages?

No. The crawler can only index publicly accessible pages. If your site has a login-protected members area, those pages won't be indexed.

Will it slow down my site?

No. The script loads asynchronously and doesn't block page rendering. The widget index (~200 KB gzipped) is loaded in the background after the page finishes loading.

What languages are supported?

Spotlight works on content in any language — English, Spanish, French, German, Japanese, and more. The AI model understands queries in the same language as your content.

Can I customize the look of the widget?

Yes. You can set the accent color with data-color. Full white-label theme customization (fonts, border radius, dark mode) is on the Pro roadmap.

What happens to my visitors' search queries?

Queries are used to generate AI answers and are stored (anonymously) so you can see what your visitors are searching for in the dashboard. No PII is collected.

Is there an API?

A REST API is on the roadmap for Pro users — to trigger re-indexing, retrieve popular queries, and push content updates without a re-crawl.

How many pages can be indexed on the free plan?

Up to 30 pages. Each page is chunked into sections, so a 30-page site might yield 150+ searchable chunks. The Pro plan supports up to 100 pages per site.

Spotlight Docs