# Search

The static search index docsp builds, what the dialog shows, and the settings that change it.

`docsp build` writes a [Pagefind](https://pagefind.app) index to `dist/pagefind/`. Search runs in the browser: there is
no search server and no request leaves the site. In `docsp dev` there is no index; build the site to try search.

## Using search

Open the dialog with the search field in the top bar or with :kbd[Ctrl] + :kbd[K] (:kbd[Cmd] + :kbd[K] on macOS).

- Results are grouped into Guides, API reference and Symbols. The group with the best match comes first.
- Each group shows five results and a "Show all" row.
- Chips with counts filter by type.
- A symbol result shows its signature, the first sentence of its documentation, its kind and its qualified name. A
  page titled exactly as the query comes first in its group.

Each locale has its own index, so a reader searches the language they are reading.

## Scope

On a project page, search starts limited to that project and the version being read. The "All projects" filter
searches the current version of every project.

| Setting | File | Effect |
|---|---|---|
| `search.crossProject` | `site.json` | `true` (default) offers the All projects filter. This site has one project and sets it to `false`. |
| `search.scope` | `project.json` | `project` (default) preselects the current project; `site` preselects all projects. |

## What is indexed

The article of every docs page, API page, release and symbol page. The code block headers, the code column of API
pages, the mobile table of contents and the article footer are left out.

## Another search engine

The client calls `window.docspSearch(query, projectId)` to get results. A script that defines this function before
the docsp client loads replaces Pagefind with another index; it must return groups of hits in the same shape (see
`packages/docsp/src/scripts/client.ts`).
