A Path is an ordered set of links to activities. Each step keeps its authored label, linked Source or instance, and progress from the installed Completion reader.
A link to a Block summarizes that Block; a Source link summarizes the Source.
# Practice
1. [First reflection](./reflection.project.md?iid=first) {#first}
2. [Take a break](./break.event.md) {#break}
3. [Reflect again](./reflection.project.md?iid=retry) {#retry}
Activate @pathmx/path in your project. To compose a Completion reader, use
createPathPlugin({ completion: completion.reader }) and register its plugin
together with the Completion plugin.
Use a Source title in frontmatter and let the step component present the heading and available metadata. It replaces the ordinary Markdown heading at that position.
---
title: Reflection
icon: pencil
---
<x-path-step />
Write one thing you would try differently.
When reached from a Path, the header uses that placement's label and effective Source instance. A direct Source visit shows its own title and metadata. Core Schedule contributes event times and deadlines; Location contributes physical and online links. Completion contributes status when configured. These use the effective instance props of the linked Source.
Put one navigation component in the shared layout:
<x-path-player />
<x-player-app />
The Path component renders a compact island with the current step's completion indicator, Source icon, title, and available schedule/location metadata. An inset track has one segment per step: accent segments show completion, a stronger neutral segment marks the current unfinished step, and remaining segments are muted. Its menu and title area open the complete outline. The outline header and close control stay visible as its step list scrolls. Previous/next controls navigate between steps. Both remain visible, with the unavailable direction disabled at the beginning or end of the Path. Without valid Path context, the island is absent; it does not guess a Path from other Sources linking here.
With Player installed, Focus and Slides show a smaller control containing the Path icon/name and previous/next chevrons in the shared control dock. It omits progress segments; selecting the Path identity opens the same outline. Step navigation preserves the chosen mode and each destination's instance. Beat navigation stays within the current Source; reaching its final Beat does not complete the activity.
The overlay's Exit Path link opens the current Source without path and
step, preserving its instance, other query parameters, and current fragment.
The full row opens a step; location links remain independent targets.
Steps without completion requirements remain navigable and use a quiet content
marker. They do not contribute to completion totals. For explicit acknowledgment,
author a Source or Block completion requirement:
completion:
label: Finish this lecture
When that acknowledgment is the remaining requirement and the viewer can update it, Path offers Complete and continue (or Complete step at the end). The action uses Completion's existing state and advances only after a confirmed save and page refresh. A failure leaves the viewer on the current step. Compact Play keeps this action in the overlay.
<x-path-list source="./practice.path.md" />
<x-path-step path="./practice.path.md" step="retry" />
<x-path-player path="./practice.path.md" step="retry" />
source and path resolve relative to the authoring Source. step names the
stable authored identifier within that Path. An explicit player must match the
Source instance being viewed. The list and outline use the same task-row renderer.
bun run pmx lint
bun run pmx lint --format json
bun run pmx query path.steps --input '{"path":"/practice.path"}'
Lint reports missing or duplicate step IDs, unsupported step tags, missing linked
Sources, nested Path cycles/repeated inclusion, and invalid component references.
For an explicit component, provide both path and step; an unknown step diagnostic
lists the IDs available in that Path. Select a step inside a nested Path by naming
that nested Path explicitly. source and path may select an existing instance
with ?iid=…; use the separate step prop rather than a URL fragment.
The path.steps query shows the admitted order, stable IDs, targets, and completion.
Use --as /people/alex.user to inspect the route through a particular viewer's
access. Querying does not change progress.