[@layout]: ../docs.layout.md

# Search

Find pages by title or content. Site Search includes pages reachable from the
homepage through Sources the current reader can access.

```sh
bun run pmx plugins add search
```

In a [Quickstart project](../start/first-site.guide.md), the command installs and
activates `@pathmx/search`. Place its trigger once in the header of the generated
`paths/site.layout.md`:

```html
<x-search-trigger />
```

Create `paths/contrast.lesson.md` with `# Contrast` and the sentence “Compare
a dark heading with a pale one.” Link to it from `paths/index.md`:

```md
[Contrast](./contrast.lesson.md)
```

Run `bun run dev`, open the home page, and
choose Search. Type “contrast”, select the result with the keyboard or touch,
and confirm `/contrast.lesson` opens. Try an unmatched term such as
“zzzz-no-match”: there are no matching results; clear it and try again.

---

## Hosting and access

Authored layout and navigation references count toward reachability. Authored
queries connect their returned internal links too, so a query-built directory
can make its entries discoverable. Query filters, sorting, limits, and the reader’s
access still apply. Unlinked
pages remain accessible by direct URL but do not appear in site Search. A link
emitted only by a Component renderer does not add a graph relation. This also
applies to a session control's Home link: readability and discovery are separate.
For reader-specific Home discovery, a Plugin can contribute
[`contextualRelations`](../extend/plugins.reference.md) after checking the target
through the admitted View; an authored link or query works for static navigation.

Live sites rank viewer-safe results on the server and return only the best 20.
Static publications fall back to one lazy client index. Normal page loads carry
neither payload. Set `search: false` in a Source’s frontmatter to omit that page
from Search; its links still contribute to reachability.

---

## Search from the terminal

With Search installed, run the same access-filtered lookup from the project root:

```sh
bun run pmx search contrast
bun run pmx search contrast --limit 10 --format json
```

Output formats are `table`, `json`, and `jsonl`. Search loads the project only
when the command runs and does not require a live server. CLI Search includes
unlinked readable pages so you can inspect the whole repository.

The result names Contrast and its route. Use `--as <actor-id>` only when you
need to inspect a specific existing Actor's access; it does not grant a browser
session or write permission. See [CLI](../cli.reference.md).