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

# Links

A relative link to an exact file is an edge in the site graph. PathMX renders the canonical route and keeps the link working in editors and on GitHub.

```md live
Read the [callouts reference](./callouts.reference.md), then the
[spec](https://spec.commonmark.org/).

[@link.button Browse examples](../../examples/index.md)
[@link.button.outline Site home](../../index.md)
```

Read the [callouts reference](./callouts.reference.md), then the
[spec](https://spec.commonmark.org/).

[@link.button Browse examples](../../examples/index.md)
[@link.button.outline Site home](../../index.md)

---

## Contract

| Syntax                                   | Meaning                                                       |
| ---------------------------------------- | ------------------------------------------------------------- |
| `[Label](./file.md)`                     | Edge to a Source. Rendered as its public route.               |
| `[Label](./file.md#block-id)`            | Edge to a Block or heading inside a Source.                   |
| `[Label](https://…)`                     | External link. Opens in a new tab with `rel="noopener"`.      |
| `[@link.button Label](./file.md)`        | Link styled as a button.                                      |
| `[@link.button.outline Label](./file.md)`| Outline button variant.                                       |
| `[@include](./file.md)`                  | Transcludes every Block of another Source.                    |
| `[@include](./file.md#block-id)`         | Transcludes one Block.                                        |
| `[Label](~/notes.md)`                    | Resolves inside the viewing Actor's home.                     |

---

## Link cards

Use `@link.card` for a Source summary that stays visible. No component import is required.

```md live
[@link.card Ada’s profile](../../examples/references/ada.badge.md)

[@link.card](./sources.reference.md)
```

[@link.card Ada’s profile](../../examples/references/ada.badge.md)

[@link.card](./sources.reference.md)

The link text supplies the title; omit it to use the destination title. Cards
show the destination’s description and image when available, plus its Map type
icon, label, and color. Descriptions are limited to three visible lines. Missing
images leave no empty thumbnail space.

Each card is one native link with hover and keyboard focus feedback. Cards do
not open another link preview. Put each card in its own paragraph, separated by
blank lines, or in its own list item. Consecutive lines form one paragraph;
`pmx lint` reports that invalid placement with a repair, and rendering rejects it.
The containing layout controls columns and spacing.

Cards support local Sources and exact Blocks, including query parameters and
fragments. A Block card uses that Block’s metadata and its Source’s Map type.
Unreadable destinations render as unavailable without exposing their metadata.
External website metadata fetching is not supported.

`card` is the built-in rich-link name; give custom imported components their own
names, such as `project-card`.

---

## Rich references

Import a Markdown component and name its tag in a link qualifier:

```md
[@people]: ../../examples/references/reference.components.md

Meet [@link.person-badge Ada](../../examples/references/ada.badge.md).
```

The complete [component definition](../../examples/references/reference.components.md#an-inline-avatar-badge)
and [Ada Source](../../examples/references/ada.badge.md) supply the template, image,
and metadata used here.

`person-badge` receives the selected Source's `title`, `description`, `image`,
and scalar authored data, plus `label` (the link text), `href` (the navigation
URL), and `source` (the canonical Source reference). Use `{{ label }}` and
`{{ href }}` in its link template. Relative images resolve beside the target.
Plugin component tags work too, such as `@link.x-books-card`.

An exact Block fragment selects that Block's metadata and data:

```md
[@link.project-entry Practice](./project.project.md#practice)
```

The Block's `source` prop includes its fragment, so a component can compose
`<x-completion-progress source="{{ source }}" />`. Completion's `progress` and
`outline` components accept the same Source/Block references. Omitting `source`
continues to show the represented page's requirements.

Rich references require local Sources or exact Blocks. Missing targets or
component imports produce diagnostics. Unreadable targets render as unavailable
without exposing their metadata. Inline references must render phrasing HTML;
put cards with articles or controls in separate paragraphs or list items.
Custom components whose output contains block HTML are checked at render time.

See [links with useful context](../../examples/references/index.demo.md) for
working avatar, project, Block, and query examples.

---

## Player links

With the Player Plugin installed, add `play` to render a compact action link
with a play icon and a mode chooser. The primary link opens Focus; the chooser
starts Focus or Slides immediately. Use `play.slides` for Slides or `play.focus` to
name Focus explicitly.

```md live
[@link.play Play the quickstart](../start/first-site.guide.md?intensity=medium#quickstart)
```

[@link.play Play the quickstart](../start/first-site.guide.md?intensity=medium#quickstart)

Link to a heading, Block, or authored Beat by adding its fragment. The link keeps
that fragment and any other query parameters, and sets `play=focus` or
`play=presentation`. It remains an ordinary link that readers can copy or open
in another tab. Include `<x-player-app />` in the destination page or its layout
to make Player available there.

---

## Link previews

Hover over an internal prose link, or focus it with the keyboard, to preview
its title and summary. A Source image appears as a thumbnail; a Block preview
also names its parent Source. Try [Ada's profile](../../examples/references/ada.badge.md).

Move into the card to keep it open. Press Escape to dismiss it, or follow the
original link or card to open the destination. Preview links preserve query
parameters and fragments, including Player mode. Touch taps open links normally.

## Notes

Ordinary page links must target a Source with a rendered page. Layout and
navigation Sources configure the site; linking to them as pages produces a
`pmx lint` diagnostic and a development-server warning. Use a code-formatted
filename when referring to one in an explanation. Layout and navigation
import declarations remain valid.

- `pmx lint` reports links to files that do not exist; `pmx mv` rewrites them when a file moves.
- An include of a Source the reader cannot access renders as an unavailable notice, not its content.

---

## Open alongside the page

Layouts can supply a reference sidebar and an overlay destination:

```md
[@link(open=reference) Keep this handy](./sources.reference.md)

[@link(open=overlay).button Open the book](../../examples/bookcase/books/neuromancer.book.md)
```

Shift-click opens an ordinary Source link as a reference when the layout supports
it. See [Opening Sources](./source-opening.guide.md) for layout setup, touch access,
and the shared browser API.


---

## Related

- [Sources](./sources.reference.md) · [Queries](./queries.reference.md)
- [Images](./images.reference.md) owns image directives, variants, and galleries.
- [Completion](../learning/completion.reference.md#progress-ui) owns progress UI and permissions.
- [Reuse content](./reuse-content.guide.md) teaches whole-Source and Block includes.
- [Source journey demo](../../examples/pathmx-source-journey.demo.md)