> ## Documentation Index
> Fetch the complete documentation index at: https://d83127a-margin.manicule.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://d83127a-margin.manicule.dev/docs/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://d83127a-margin.manicule.dev/docs/api/mcp.
> Every agent surface: https://d83127a-margin.manicule.dev/docs/.well-known/llms-manifest.json

# Configure documentation search (/docs/customize/search)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1123 · updated: 2026-11-09 -->
Related: [Set logos, favicons, and icons](/docs/customize/branding.md), [Customize CSS and layout](/docs/customize/css.md), [Configure site fonts](/docs/customize/fonts.md), [Redirect moved pages](/docs/customize/redirects.md), [Configure SEO and metadata](/docs/customize/seo.md), [Set colors and themes](/docs/customize/themes.md)

> Choose the search interface and predict which versions and languages appear in results.

Set `x-margin.search.mode` in `docs.json` to choose documentation search with an AI assistant, plain text search, or no search interface.

## Choose a search mode

Choose `static` when readers need matching pages without generated answers. Choose `ai` when readers should also be able to ask questions and receive answers with source links.

| Mode     | Reader experience                                                                            | Prerequisites                                                                                              |
| -------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `ai`     | Documentation search plus an AI assistant that cites source pages. This is the default mode. | AI Gateway access for the assistant. Without deployment credentials, the interface falls back to `static`. |
| `static` | Text search over indexed page titles, headings, and content. No assistant controls.          | No AI credentials.                                                                                         |
| `off`    | No search dialog or assistant controls.                                                      | No AI credentials.                                                                                         |

On self-hosted deployments outside Vercel, set `AI_GATEWAY_API_KEY` in the server environment to use the assistant. On Vercel, enable AI Gateway access for the deployment; the assistant can use Vercel OIDC authentication. Do not put the credential in `docs.json`.

The credential fallback applies when the deployment has no assistant credentials. It is not a guarantee that failed model requests automatically become text-search results. Set `static` explicitly if the site should never offer AI answers.

## Set the search configuration

Merge this fragment into the site's existing `docs.json` to select static search. Preserve the other configuration fields.

```json title="docs.json"
{
  "x-margin": {
    "search": {
      "mode": "static"
    }
  }
}
```

The `search` field is an object with an optional `mode` field. Accepted values are exactly `ai`, `static`, and `off`. Omitting `mode`, `search`, or the entire `x-margin` block selects `ai`, subject to the credential fallback above.

Publish the configuration change through the site's normal deployment process. On the deployed site, open search and query a known page title. With `static`, matching pages should appear without assistant controls. With `ai` and working AI Gateway access, the assistant should also be available. With `off`, the search dialog should be unavailable.

`off` removes the reader-facing search interface; it does not disable the `/api/search` endpoint. Do not use this setting as a content-access restriction.

## Understand version and locale scope

Search follows the version and locale of the page the reader is viewing. The assistant's documentation search uses the same scope as text search, so enabling AI does not broaden results to all versions or languages.

A recognized non-default locale prefix selects that locale. Without a locale prefix, search uses the default locale. Within that locale, a recognized version prefix selects that product version; an unprefixed path uses the locale's default version. If no version is marked as default, Margin selects the first local version, when one exists.

The index includes pages assigned to the selected version and shared pages that have no product-version assignment, all within the selected locale. Other product versions and locales are excluded. Search does not fill missing translations with pages from the default locale or retry an empty result across other versions. Readers must switch version or language to search another scope.

Search also applies page-indexing rules. Hidden pages remain searchable when marked `searchable`; the site-wide `seo.indexing: "all"` setting also includes hidden pages. Synthesized pages are excluded. Hiding a page from navigation alone does not necessarily remove it from search.

To check scope after deployment, search for a term unique to one version or locale, then repeat after switching the version or language. Shared pages may appear in more than one version's results.