Reuse content

Include a complete Block when the same instructions belong in several places. Edit the owner once and its consumers update together.

Keep each page's purpose and next step local so the reused content fits its reader's task.

The Input and Completion references both need the same explanation of writable personal storage. Personal Sources owns that explanation; both pages include it. The walkthrough below uses those actual public docs files.

In docs/extend/state.reference.md, the shared Block follows a --- boundary:

---

<!-- id: storage-requirements -->

## Before saving personal work

Saving a response, progress, or an attachment requires an admitted Actor and a
writable Home. Use the [local account setup](../accounts/auth.reference.md#local-actor)
for development, then configure credentials and persistent writable storage for
shared hosting. A [browser publication](./core.reference.md#browser-publications)
provides a local Actor and writable Home on one device without sign-in; its saved
files do not synchronize to a server. An ordinary static export does not provide
a writable Source host. Disposable drafts and device settings are separate from
committed work.

The id belongs in the Block's leading comment. A heading alone is not a separate Block. Keep the id stable when other Sources refer to it.

In docs/authoring/input.reference.md, the consumer uses:

[@include](../extend/state.reference.md#storage-requirements)

docs/learning/completion.reference.md uses the same relative reference. The rendered result is the owner's complete heading and explanation:

Open Input forms and Completion to see that Block before their examples. During bun run dev, changing the owner's explanation updates both open consumers. Keep the domain-specific save and recovery instructions on each consumer page.

To try this in your own project, create an owner such as paths/setup.page.md with the Block above and replace its prerequisite links with your site's actual Sources. Create paths/lesson.page.md with a title and [@include](./setup.page.md#storage-requirements). Run bun run dev, open /lesson.page, edit the owner, and observe the consumer update.

The Paper and Terminal examples include the same complete theme specimen. Each consumer keeps its theme choice local. Quickstart remains the owner of initial project commands; link to it when another page does not need to repeat the whole tutorial.

Linking to the same Source shares its content and saved work. Add a different iid when you want a separate use, with its own settings and saved work.

For example, write the shared instructions in paths/reflection.project.md:

# Reflection

Write one thing you would try differently.

<x-input-textarea name="answer" label="Your reflection" />
<x-input-submit label="Save reflection" />

Then link to two attempts from a course page:

[First attempt](./reflection.project.md?iid=first)
[Retry](./reflection.project.md?iid=retry)

Both use the same instructions. With writable Actor storage, each learner has a separate response for each attempt. Linking to ?iid=first elsewhere opens the same first attempt; it does not create another one. You can include that attempt with [@include](./reflection.project.md?iid=first).

With the Path and Actor Completion plugins, use the same links as ordered Steps in a .path.md Source:

# Reflect and try again

1. [First reflection](./reflection.project.md?iid=first) {#first}
2. [Reflect again](./reflection.project.md?iid=retry) {#retry}

Each Step shows that attempt’s completion. Step links preserve the selected instance and Path context for previous/next navigation. A named Path does not create separate attempts for its children: the child links still choose their instances. Two Paths linking to ?iid=first share the same first attempt.

The ordinary link without iid keeps its existing saved work. Changing it to a named instance selects separate work; it does not copy or migrate old responses. Plugins may also permit named instances to override settings, such as an event's start time. Object fields use dotted names, such as ?iid=retry&options.label=Retry; other fields keep their Source defaults. The owning plugin defines which props and values are allowed; see instance props.

Live sites render the selected instance on the server. Static export includes public instance representations; its browser runtime selects them at the same query URL, which requires JavaScript for direct navigation. Included instances are already rendered in the exported HTML. Saving still requires the existing personal-storage setup.

Relative links, assets, and component declarations inside the included content belong to its owning Source. Keep the owner's dependencies obtainable alongside it; copying only a consumer does not copy the files it includes. Includes do not install packages or activate Plugins.

Use the owner's canonical Source and stable Block fragment for direct links to shared instructions. Do not assume repeated includes create a new author-defined namespace for headings or ids. Prefer one inclusion of a given Block per consumer when readers need a single unambiguous destination.

Missing targets and invalid fragments render Broken Include; embedding across an unavailable access boundary renders Unavailable Include. Correct the target, fragment, or access at its owner. A reader must be allowed to read the included Source and its dependencies; an include cannot expose private setup to an anonymous reader. Check the rendered consumer and diagnostics when the target is unavailable.

Review the owner and each consumer in reading, Focus, and Slides. The included Block should be a useful step without duplicate page titles or unrelated setup. Check its links and assets, and verify live edits and static export after a change.

Fetch the consumer's delivered Markdown alternate:

curl -fsS https://docs.pathmx.dev/docs/authoring/input.reference.md

If the response contains the include declaration, follow its exact relative Source target and select the Block by its leading id. The declaration is a dependency, not evidence that its body has been expanded. Read the owner's requirements before applying the consumer's example.

• Blocks · Links
• Components