HTML / other CMS

Add cited search to any site that has a JavaScript build step, such as Hugo, Jekyll, Eleventy, Ghost or a Drupal theme, with one custom element.

Custom elementDeveloper preview@docslurp/sdk/widgetAll integrations

On this page

1Install

TerminalShell

# Needs @docslurp/sdk 0.2.0 or newer (0.1.x lacks these exports).
npm install @docslurp/sdk@^0.3.0

# Then register the element once in the browser:
# import { defineDocSlurpSearch } from '@docslurp/sdk/widget';

2Register the element

Bare npm imports need a bundler or import map, so register the widget in your existing build rather than pasting it into an unconfigured page.

site.jsJavaScript

import { defineDocSlurpSearch } from '@docslurp/sdk/widget';

defineDocSlurpSearch(); // call once, from your site's existing bundle

3Render it

Place the element in any template, using your template engine’s escaping for attribute values.

search.htmlHTML

<docslurp-search-box
  client-key="dslp_pub_…"
  workspace-id="product-docs"
  placeholder="Search the manuals…"
></docslurp-search-box>

Attributes

Attribute	Default	Description
`client-key`	`Required*`	Browser key with the search scope, limited to your allowed websites.
`workspace-id`	`"default"`	Workspace slug, UUID or default.
`api-url`	`"https://docslurp.io"`	DocSlurp origin, for self-hosted deployments.
`search-endpoint`	`none`	Your own server proxy. Replaces client-key, api-url and workspace-id.
`placeholder`	`"Search documents…"`	Input placeholder text.

* Not needed when search-endpoint is set.

Private content

For content behind a login, point the element at your own endpoint. Your server authenticates the visitor, picks the workspace they may read, searches with a server key and returns the results. The Next.js guide has a complete route handler.

search.htmlHTML

<!-- Your server receives POST { "q": "…" } and returns { "results": [...] }. -->
<docslurp-search-box search-endpoint="/api/search"></docslurp-search-box>

Styling

The element renders in a shadow root and shows passage text as plain text nodes, so source content can’t inject markup. Theme it with two custom properties:

site.cssCSS

docslurp-search-box {
  --docslurp-text: #e2e8f0;
  --docslurp-background: #0b1220;
}

Hand off to an agent

Working in a real codebase? Copy a prompt that tells a coding agent exactly what to change for HTML / other CMS: which entry point to use, the supported contract, and what to validate before shipping. It contains no keys or secrets.

Review agent instructions

Integrate DocSlurp search into this project's HTML / other CMS surface.

Read https://docslurp.io/docs/search-integrations/html and inspect the project's current search calls, framework version and source routing. Preserve its UI, accessibility and keyboard behavior.

Bundle @docslurp/sdk/widget in the existing asset pipeline, call defineDocSlurpSearch once, and render docslurp-search-box with an escaped client-key attribute (workspace-id defaults to the default workspace of the key organization; api-url to https://docslurp.io). Bare npm imports need a bundler/import map. Use a public-content workspace and restricted search-only client key.

Package availability: the SDK subpaths and dedicated compatibility/Astro packages require version 0.2.0 or newer (see https://docslurp.io/docs/packages); verify installed version/exports before using them. Never install a nonexistent package based on this prompt.

Required configuration (use placeholders/secret configuration, never include secret values in this prompt): DocSlurp API origin, workspace ID, appropriate search-only key, public source URL map. Ingest the corpus with native SDK upload/URL ingestion and wait for completion. Do not invent an ingestion or post-sync feature.

Search adapters replace documented read-side calls only. Meilisearch/Typesense/Pagefind counts represent a bounded 100-passage window, not exact corpus totals. Empty queries return no results. Reject unsupported options; do not silently drop filters, facets or sorting. Escape result text/HTML and verify source links. Private corpora require authenticated access checks.

Validate normal/Unicode queries, no matches, empty query, errors, cancellation, pagination limits, mobile layout, key-domain/workspace restrictions and the actual build. Report files changed, tests run, supported contracts and remaining migration gaps. Do not publish credentials or deploy without the project's authorization.

Before switching traffic, run through the go-live checklist. Stuck? See troubleshooting.