Reef Search Documentation

Welcome to the official documentation for Reef Search. This guide covers everything from basic installation to advanced configuration and integration.

What is Reef Search?

Reef Search is a zero-build, client-side search overlay designed for static websites. It transforms a simple <script> tag into a powerful, keyboard-first search experience that indexes your content entirely in the visitor's browser.

Key Characteristics

  • Zero backend required — No servers, no database, no external API calls
  • Privacy-first — All indexing and search happens locally in the browser
  • Framework agnostic — Works with plain HTML, React, Vue, Svelte, or any framework
  • Keyboard-first UX — Press ⌘K or Ctrl+K to open the search modal
  • Small footprint — Approximately 6.2KB gzipped (excluding fonts)

Core Philosophy

Reef Search was built on the principle that static sites deserve better search without the complexity. Traditional search solutions require:

  1. Account registration and dashboard configuration
  2. Server-side indexing and query processing
  3. Monthly fees based on usage volume
  4. Privacy concerns as all queries are logged

Reef Search eliminates all of these requirements while providing a search experience that rivals hosted solutions.

How It Works: Architecture Deep Dive

System Architecture

Reef Search consists of four main components working in harmony:

1. Loader (loader.ts)

Entry point that reads configuration from script attributes, registers the Cmd+K/Ctrl+K hotkey, and initializes the search system during browser idle time.

2. Crawler/Indexer (search.ts)

Discovers pages via sitemap.xml, fetches content via fetch API, and extracts searchable content using DOMParser.

3. Index Store (search.ts)

In-memory search index with optimized data structures for fast querying. Supports multiple record types with weighted scoring.

4. UI Layer (reef.ts)

Shadow DOM-based modal overlay with keyboard navigation, result rendering, and action execution capabilities.

Initialization Flow

When you include Reef Search on a page, the following sequence occurs:

  1. Script Load — The browser downloads reef.min.js from your server or CDN
  2. Configuration Parse — The loader reads data-* attributes from the script tag
  3. Hotkey Registration — Listens for ⌘K/Ctrl+K to open the modal
  4. Sitemap Fetch (if available) — Retrieves sitemap.xml to discover all pages
  5. Parallel Page Fetching — Fetches up to 6 pages concurrently (configurable via data-max-pages)
  6. Content Extraction — Parses each page's HTML and extracts headings, body text, and other content types
  7. Index Building — Tokenizes all content into an in-memory search index
  8. User Interaction — Search queries run against the in-memory index with fuzzy matching

Data Structures

The search index uses three primary data structures for efficient querying:

// headingIds: Map<string, IndexRecord[]>
// Stores records indexed by exact heading text (lowercase)
// Example: "installation" → [record1, record2]

// headingIndex: Map<string, IndexRecord[]>
// Stores records indexed by heading text prefixes
// Enables fast prefix matching for autocomplete-style search

// bodyIndex: Map<string, IndexRecord[]>
// Stores records indexed by individual body text words (3+ chars)
// Used for full-text search within page content

Universal Record Types

Overview

Reef Search supports seven distinct record types, each with specific extraction rules and interaction behaviors:

Type Icon Description Behavior
section 📄 Page headings and their associated body text Navigate to page and scroll to heading anchor
action ⚡ Clickable elements: buttons, toggles, summaries Execute click event on current page, or navigate with deferred execution
field 📝 Form inputs, textareas, and select elements Focus the element (and select its content)
link 🔗 External links (different origin than current page) Navigate to the linked page
file 📎 Downloadable resources (PDF, DOC, XLS, etc.) Navigate to download the file
media 🎵 Images with alt text and video/audio with transcripts Navigate and highlight the media element
structured 🔍 FAQ entries and other JSON-LD structured data Navigate to the FAQ or structured data location

Scoring Algorithm

Search results are ranked using weighted scoring based on match type:

Match Type Score Description
Exact heading match 100 Perfect match on heading text
Heading prefix match 50 Query matches beginning of heading
Body word match 20 Query appears in section body text
Fallback substring 40 / 10 Substring match in heading/body as last resort

Destructive Action Detection

Actions with labels containing certain keywords are treated as destructive and excluded from automatic execution:

const destructiveVerbs = [
  'delete', 'remove', 'cancel subscription', 'unsubscribe',
  'pay', 'checkout', 'submit order', 'confirm'
];

When an action is marked destructive, the search will navigate to the page instead of executing immediately, allowing the user to confirm the action visually.

Use Cases

Documentation Sites

The primary use case for Reef Search is documentation websites. It excels at:

Blog Search

For personal blogs and articles, Reef Search enables:

Knowledge Bases

Internal or external knowledge bases benefit from:

E-commerce Product Search

Small catalog sites can use Reef Search for:

Dashboard Action Search

⚠️ Important Security Note

When using action indexing on interactive sites, Reef Search provides:

Quick Start

Ready to add search to your site? Here's the fastest path:

<script src="https://unpkg.com/reef-search/dist/reef.min.js"></script>

That's it. Reef Search will automatically:

Having trouble? Installation guide → covers troubleshooting, CDN options, and framework-specific setups.