[@layout]: ../docs.layout.md # 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](../extend/state.reference.md#storage-requirements) owns that explanation; both pages include it. The walkthrough below uses those actual public docs files. --- ## Give the owner a stable Block id In `docs/extend/state.reference.md`, the shared Block follows a `---` boundary: ```md --- ## 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. --- ## Include it where readers need it In `docs/authoring/input.reference.md`, the consumer uses: ```md [@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: [@include](../extend/state.reference.md#storage-requirements) Open [Input forms](./input.reference.md) and [Completion](../learning/completion.reference.md) 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. --- ## Choose a link, include, component, or embed | Need | Use | | --- | --- | | Send someone to setup or deeper reference | An ordinary descriptive link. | | Repeat the same explanation or complete example | `[@include](./owner.md#block-id)`. | | Reuse every Block of another Source | `[@include](./owner.md)`, without a fragment. | | Repeat presentation with different content | A [literate component](./components.reference.md#markdown-components) with slots. | | Keep an independent page's styles, scrolling, and interactions | A [Source embed](./components.reference.md#source-embeds). | The [Paper](../../examples/themes/paper.md) and [Terminal](../../examples/themes/terminal.md) examples include the same complete [theme specimen](../../examples/themes/gauntlet.md). 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. --- ## Reuse a Source as separate attempts 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`: ```md # Reflection Write one thing you would try differently. ``` Then link to two attempts from a course page: ```md [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: ```md # 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](../extend/plugins.reference#schemas-queries-and-bindings). 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](../extend/state.reference#storage-requirements). --- ## Preserve ownership and access 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. --- ## Check reading, Play, and Markdown 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: ```sh 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. --- ## Related - [Blocks](./blocks.reference.md) · [Links](./links.reference.md) - [Components](./components.reference.md)