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.
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, then the spec.
| 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. |
Use @link.card for a Source summary that stays visible. No component import is required.
[@link.card Ada’s profile](../../examples/references/ada.badge.md)
[@link.card](./sources.reference.md)
Sources
A Source is one Markdown file under paths/. Its filename gives it a name, a type, and a route; frontmatter adds metadata.
Reference
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.
Import a Markdown component and name its tag in a link qualifier:
[@people]: ../../examples/references/reference.components.md
Meet [@link.person-badge Ada](../../examples/references/ada.badge.md).
The complete component definition and Ada Source 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:
[@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="" />. 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 for working avatar, project, Block, and query examples.
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.
[@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.
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.
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.
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 lintreports links to files that do not exist;pmx mvrewrites them when a file moves.- An include of a Source the reader cannot access renders as an unavailable notice, not its content.
Layouts can supply a reference sidebar and an overlay destination:
[@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 for layout setup, touch access, and the shared browser API.
- Sources · Queries
- Images owns image directives, variants, and galleries.
- Completion owns progress UI and permissions.
- Reuse content teaches whole-Source and Block includes.
- Source journey demo