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

# Graph

Show local Source connections as backlinks, an inline graph, or a dialog.
Install the optional Graph package:

```sh
bun run pmx plugins add graph
```

The command installs and activates Graph in your project.

---

## Show connections

Start in an initialized [Quickstart project](../start/first-site.guide.md).
Create `paths/contrast.lesson.md`:

```md
# Contrast

Compare dark and light headings.

[Try spacing](./spacing.lesson.md).

<x-graph-view />
```

Create `paths/spacing.lesson.md`:

```md
# Spacing

Give the heading room above and below it.

<x-graph-backlinks />
```

Run `bun run dev` and open `/contrast.lesson`: Contrast connects to Spacing.
Open Spacing to see Contrast as a backlink. Remove the link from Contrast and
save: that connection and backlink disappear. Restore it before trying the
neighborhood controls below.

To show the same graph on every page, place it once in the shared layout instead:

```html
<x-graph-view />
```

It centers on the represented page, including when authored in a shared layout.
Ordinary Markdown links supply the default connections. The view shows up to
50 readable pages, with titles and type descriptors from the site's Map.

Use a trigger for a compact dialog, or backlinks for incoming links:

```html
<x-graph-backlinks>
  <slot name="actions"><x-graph-trigger /></slot>
</x-graph-backlinks>
```

Backlinks show each readable linking page once, sorted by title. Empty backlinks
disappear while the optional action remains available. Backlinks alone do not
load graph JavaScript.

---

## Choose the neighborhood

```html
<x-graph-view
  root="./graph.reference.md"
  depth="2"
  direction="both"
  relations="link"
/>
```

All three components accept `root` and `relations`. View and trigger also accept
`depth` and `direction`; `label` belongs to the trigger.

- `root`: Source path, resolved beside the authored component when relative.
  Defaults to the represented page.
- `relations`: Space-separated relation names; defaults to `link`.
- `depth`: `1` or `2` connection levels; defaults to `1`.
- `direction`: `incoming`, `outgoing`, or `both`; defaults to `both`.
- `label`: Accessible name and tooltip; defaults to “Explore connections”.

Backlinks always show one level of incoming connections. Graph filters unreadable
Sources before traversing their connections, so hidden pages do not expose labels
or bridge to other pages. It is a local view, not a whole-repository graph editor.

---

## Navigate and host

Select a node by clicking it or pressing Enter/Space, then follow its title link
to open the Source. Select it again or press Escape while focused to clear it.
The connection list provides ordinary links with full titles.

Drag the canvas to pan. Wheel/trackpad scrolling pans; Ctrl/Command-wheel or
trackpad pinch zooms around the pointer. Arrow keys pan, plus/minus zoom, and
zero fits the graph. Keyboard shortcuts work in the open dialog or on the
focused inline canvas. The toolbar also provides zoom, Fit, and connection-list
controls; narrow views open the list by default.

Graph works with live serving and static export, without a persistence service
or request-only endpoint. Exported connections reflect the export's viewer access.
Without JavaScript, linked navigation remains available and the trigger uses a
native disclosure. Pages without Graph components load no graph renderer.

See [Links](../authoring/links.reference.md) for authored relationships and
[Sources](../authoring/sources.reference.md) for Source types.