@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.12

package/agent-docs/author/components/walkthroughs.sections/choose-a-layout.md

@@ -0,0 +1,141 @@
+---
+id: guide.component.walkthrough
+title: Walkthroughs
+summary: Build code tutorials that explain code one step at a time, with a
+  scrolling pane in HTML and every step in Markdown.
+type: reference
+area: components
+subarea: components-code
+canonical: /author/components/walkthroughs
+---
+
+# Walkthroughs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/components/walkthroughs.md)
+
+Use `<Walkthrough>` to explain code step by step. Each step pairs an explanation with code built up across steps or read from a project file.
+
+When there is room for two columns, explanations scroll on the left and code stays on the right. Scrolling or selecting a step updates the code pane. At either end, scrolling continues through the page. On narrower screens, each step shows its explanation and code in order.
+
+The [spotlight layout](https://www.shoalrun.com/author/components/walkthroughs.md#choose-a-layout) uses step buttons instead of a scroller. Code that stays the same between steps slides to its new position, so readers can follow the changes.
+
+Use a walkthrough when readers build up code or study one file in parts. For steps without code, use an ordinary numbered list.
+
+## Choose a layout
+
+The default `scroll` layout suits code that grows as readers scroll. Set `layout="spotlight"` for reference material that readers jump around in. Step titles become buttons, and only the chosen step shows its explanation. Up and Down move between the buttons. The walkthrough below reads Shoalrun's [minimal example config](https://www.shoalrun.com/config/examples.md) straight from its file:
+
+```mdx
+<Walkthrough title="Read the minimal config" layout="spotlight" file="../examples/minimal-config.yaml">
+<Step title="Name the site" highlight="4-5">
+
+...
+
+</Step>
+</Walkthrough>
+```
+
+**Walkthrough: Read the minimal config**
+
+```yaml filename="minimal-config.yaml"
+# The smallest useful site: one publication, two pages, a sidebar.
+schemaVersion: 1
+
+site:
+  title: Acme handbook
+
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+
+# Every page gets these values unless it sets its own.
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    access: { policy: public }
+
+navigation:
+  - id: welcome
+    doc: guide.welcome
+  - id: setup
+    label: Setup
+    items:
+      - id: install
+        doc: guide.install
+```
+
+### Step 1: Name the site
+
+`site.title` appears in the header and in every page title. It is the only required site setting.
+
+Lines 4–5:
+
+```yaml
+site:
+  title: Acme handbook
+```
+
+### Step 2: Publish one edition
+
+One channel and one version, both without a path prefix, publish every page at its own slug. Add channels or versions later to publish sandbox docs or older releases beside it.
+
+Lines 7–14:
+
+```yaml
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+```
+
+### Step 3: Set page defaults
+
+Values under `frontmatter.defaults` apply to every page that doesn't set its own, so pages can leave out the type, publication, and access.
+
+Lines 16–22:
+
+```yaml
+# Every page gets these values unless it sets its own.
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    access: { policy: public }
+```
+
+### Step 4: Build the sidebar
+
+Navigation lists pages by stable ID, not by file name. `items` makes a group with a label.
+
+Lines 24–31:
+
+```yaml
+navigation:
+  - id: welcome
+    doc: guide.welcome
+  - id: setup
+    label: Setup
+    items:
+      - id: install
+        doc: guide.install
+```

package/agent-docs/author/components/walkthroughs.sections/explain-one-file.md

@@ -0,0 +1,126 @@
+---
+id: guide.component.walkthrough
+title: Walkthroughs
+summary: Build code tutorials that explain code one step at a time, with a
+  scrolling pane in HTML and every step in Markdown.
+type: reference
+area: components
+subarea: components-code
+canonical: /author/components/walkthroughs
+---
+
+# Walkthroughs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/components/walkthroughs.md)
+
+Use `<Walkthrough>` to explain code step by step. Each step pairs an explanation with code built up across steps or read from a project file.
+
+When there is room for two columns, explanations scroll on the left and code stays on the right. Scrolling or selecting a step updates the code pane. At either end, scrolling continues through the page. On narrower screens, each step shows its explanation and code in order.
+
+The [spotlight layout](https://www.shoalrun.com/author/components/walkthroughs.md#choose-a-layout) uses step buttons instead of a scroller. Code that stays the same between steps slides to its new position, so readers can follow the changes.
+
+Use a walkthrough when readers build up code or study one file in parts. For steps without code, use an ordinary numbered list.
+
+## Explain one file
+
+Put one code fence directly inside `<Walkthrough>`, before the steps, to explain a single file. Steps then have no code of their own. Each step's `highlight` picks the lines it explains.
+
+### MDX source: explain one file
+
+This source defines the interactive example below.
+
+````mdx
+<Walkthrough title="Read a retry policy">
+
+```yaml title="retry.yaml"
+retry:
+  attempts: 5
+  backoff: exponential
+  initialDelay: 2s
+  maxDelay: 5m
+```
+
+<Step title="Set the number of attempts" highlight="2">
+
+Five attempts cover most short outages.
+
+</Step>
+<Step title="Choose the delay" highlight="3-5">
+
+Each retry waits twice as long, from two seconds up to five minutes.
+
+</Step>
+</Walkthrough>
+````
+
+**Walkthrough: Read a retry policy**
+
+```yaml title="retry.yaml"
+retry:
+  attempts: 5
+  backoff: exponential
+  initialDelay: 2s
+  maxDelay: 5m
+  retryOn:
+    - 429
+    - 503
+    - timeout
+deadLetter:
+  queue: webhooks-failed
+  keep: 14d
+```
+
+### Step 1: Set the number of attempts
+
+Five attempts cover most short outages without hiding a real failure.
+
+Line 2:
+
+```yaml
+  attempts: 5
+```
+
+### Step 2: Choose the delay
+
+Each retry waits twice as long as the one before, from two seconds up to five minutes.
+
+Lines 3–5:
+
+```yaml
+  backoff: exponential
+  initialDelay: 2s
+  maxDelay: 5m
+```
+
+### Step 3: Pick what to retry
+
+Retry rate limits, unavailable services, and timeouts. Other errors fail at once, because retrying won't fix them.
+
+Lines 6–9:
+
+```yaml
+  retryOn:
+    - 429
+    - 503
+    - timeout
+```
+
+### Step 4: Keep failures
+
+Requests that use every attempt go to a separate queue for 14 days, so you can replay them.
+
+Lines 10–12:
+
+```yaml
+deadLetter:
+  queue: webhooks-failed
+  keep: 14d
+```

package/agent-docs/author/components/walkthroughs.sections/html-markdown-and-agents.md

@@ -0,0 +1,38 @@
+---
+id: guide.component.walkthrough
+title: Walkthroughs
+summary: Build code tutorials that explain code one step at a time, with a
+  scrolling pane in HTML and every step in Markdown.
+type: reference
+area: components
+subarea: components-code
+canonical: /author/components/walkthroughs
+---
+
+# Walkthroughs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/components/walkthroughs.md)
+
+Use `<Walkthrough>` to explain code step by step. Each step pairs an explanation with code built up across steps or read from a project file.
+
+When there is room for two columns, explanations scroll on the left and code stays on the right. Scrolling or selecting a step updates the code pane. At either end, scrolling continues through the page. On narrower screens, each step shows its explanation and code in order.
+
+The [spotlight layout](https://www.shoalrun.com/author/components/walkthroughs.md#choose-a-layout) uses step buttons instead of a scroller. Code that stays the same between steps slides to its new position, so readers can follow the changes.
+
+Use a walkthrough when readers build up code or study one file in parts. For steps without code, use an ordinary numbered list.
+
+## HTML, Markdown, and agents
+
+Before scripts run, the HTML shows every step in order with its code. On screens too narrow for two columns, it stays that way. Readers who prefer reduced motion get the same pane without the movement.
+
+In the side-by-side layout, each step's own code stays in the page but out of sight. Screen readers still hear code beside its explanation. The steps scroll with a mouse wheel or trackpad while the pointer is over the walkthrough. The pane's code is a labeled region that keyboard users can focus and scroll. Its **Copy** button copies the code on show and announces the result. Dimmed lines keep at least 4.5:1 contrast in every built-in palette. To change how far other lines fade, set `--walkthrough-dim` in [project CSS](https://www.shoalrun.com/author/css.md).
+
+The Markdown twin replaces the pane with sections. The title becomes a bold line, and each step becomes a level-three heading such as `### Step 2: Check the signature`, followed by its explanation and its complete code. For a walkthrough with shared code, the code appears once before the steps. Each step then repeats the lines it explains, so an agent can quote a step without the rest of the file.

package/agent-docs/author/components/walkthroughs.sections/related-reading.md

@@ -0,0 +1,36 @@
+---
+id: guide.component.walkthrough
+title: Walkthroughs
+summary: Build code tutorials that explain code one step at a time, with a
+  scrolling pane in HTML and every step in Markdown.
+type: reference
+area: components
+subarea: components-code
+canonical: /author/components/walkthroughs
+---
+
+# Walkthroughs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/components/walkthroughs.md)
+
+Use `<Walkthrough>` to explain code step by step. Each step pairs an explanation with code built up across steps or read from a project file.
+
+When there is room for two columns, explanations scroll on the left and code stays on the right. Scrolling or selecting a step updates the code pane. At either end, scrolling continues through the page. On narrower screens, each step shows its explanation and code in order.
+
+The [spotlight layout](https://www.shoalrun.com/author/components/walkthroughs.md#choose-a-layout) uses step buttons instead of a scroller. Code that stays the same between steps slides to its new position, so readers can follow the changes.
+
+Use a walkthrough when readers build up code or study one file in parts. For steps without code, use an ordinary numbered list.
+
+## Related reading
+
+### Related topics
+
+- [Code blocks](https://www.shoalrun.com/author/components/code-blocks.md) — Walkthroughs build on code blocks to explain an example one step at a time.

package/agent-docs/author/components/walkthroughs.sections/syntax.md

@@ -0,0 +1,51 @@
+---
+id: guide.component.walkthrough
+title: Walkthroughs
+summary: Build code tutorials that explain code one step at a time, with a
+  scrolling pane in HTML and every step in Markdown.
+type: reference
+area: components
+subarea: components-code
+canonical: /author/components/walkthroughs
+---
+
+# Walkthroughs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/components/walkthroughs.md)
+
+Use `<Walkthrough>` to explain code step by step. Each step pairs an explanation with code built up across steps or read from a project file.
+
+When there is room for two columns, explanations scroll on the left and code stays on the right. Scrolling or selecting a step updates the code pane. At either end, scrolling continues through the page. On narrower screens, each step shows its explanation and code in order.
+
+The [spotlight layout](https://www.shoalrun.com/author/components/walkthroughs.md#choose-a-layout) uses step buttons instead of a scroller. Code that stays the same between steps slides to its new position, so readers can follow the changes.
+
+Use a walkthrough when readers build up code or study one file in parts. For steps without code, use an ordinary numbered list.
+
+## Syntax
+
+```mdx
+<Step title="Check the signature" file="../../examples/webhook.ts" region="verify" highlight="2-4">
+
+Compare the header with a signature of the body.
+
+</Step>
+```
+
+| Attribute | Meaning                                                                                                                                             |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `file`    | Path to the code file, relative to the page. The pane and code toolbar show the file name.                                                          |
+| `region`  | Optional. Takes the lines between a `#region name` comment and its `#endregion` comment, without the markers, and removes their shared indentation. |
+| `lines`   | Optional. Takes one range of lines, such as `12-30`. Use `region` or `lines`, not both.                                                             |
+| `lang`    | Optional. The code language, when the file extension doesn't name one.                                                                              |
+
+Prefer `region` for files that change. Region comments move with the code, while a `lines` range points at the wrong lines after an edit above it. Line numbers in `highlight` count from the first line shown, not from the top of the file.
+
+Most languages accept region comments, such as `// #region verify` in TypeScript or `# region verify` in Python and YAML. A marker starts its line, after an optional comment opener, so `#region` inside code or a URL doesn't count. The name is the first word, and text after it, such as `// #region verify: check the signature`, is a description. Regions can nest, and an end marker can repeat its name, such as `// #endregion verify`, to show which region it closes. Give each region its own name. Every marker in the file must pair up. A stray or mismatched `#endregion` fails the build with its line number instead of cutting a region short. A file must be inside the Git repository that holds the page, or inside the project directory when there is no repository. The build refuses other paths, so a docs change can't publish files from elsewhere on the build machine. A missing file, region, or range fails the build. Files the walkthrough reads are listed as build dependencies, and `shoalrun dev` rebuilds when one inside the project changes.

package/agent-docs/author/components/walkthroughs.sections/take-code-from-a-file.md

@@ -0,0 +1,34 @@
+---
+id: guide.component.walkthrough
+title: Walkthroughs
+summary: Build code tutorials that explain code one step at a time, with a
+  scrolling pane in HTML and every step in Markdown.
+type: reference
+area: components
+subarea: components-code
+canonical: /author/components/walkthroughs
+---
+
+# Walkthroughs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Walkthroughs
+
+**Updated: 2026-10-27.**
+
+Parent page: [Full Markdown page](/author/components/walkthroughs.md)
+
+Use `<Walkthrough>` to explain code step by step. Each step pairs an explanation with code built up across steps or read from a project file.
+
+When there is room for two columns, explanations scroll on the left and code stays on the right. Scrolling or selecting a step updates the code pane. At either end, scrolling continues through the page. On narrower screens, each step shows its explanation and code in order.
+
+The [spotlight layout](https://www.shoalrun.com/author/components/walkthroughs.md#choose-a-layout) uses step buttons instead of a scroller. Code that stays the same between steps slides to its new position, so readers can follow the changes.
+
+Use a walkthrough when readers build up code or study one file in parts. For steps without code, use an ordinary numbered list.
+
+## Take code from a file
+
+Code in a fence can drift from the code your project runs and tests. To show the real file instead, set `file` on a `<Step>` in place of its code fence, or on `<Walkthrough>` in place of its shared fence. The path is relative to the page.

package/agent-docs/author/components.md

@@ -0,0 +1,81 @@
+---
+id: guide.components
+title: Component reference
+summary: Find a dedicated guide for every supported MDX component and code block.
+type: reference
+area: components
+subarea: components-overview
+canonical: /author/components
+---
+
+# Component reference
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Components > Overview
+
+**Updated: 2026-10-27.**
+
+Shoalrun accepts GitHub Flavored Markdown (tables, task lists, strikethrough, footnotes, and autolinks) and the MDX components below. Each component family has a page with syntax, attributes, HTML and Markdown behavior, and limits. Component names and attributes are case-sensitive. Unknown components, dynamic MDX expressions, and exports fail the build because they have no shared HTML and Markdown representation. The build drops `import` lines, so imported components are not available.
+
+[Custom components](https://www.shoalrun.com/author/components/custom.md) let trusted project plugins lower into the shared content pipeline.
+
+[Navigation and breadcrumbs](https://www.shoalrun.com/author/navigation.md) are configured site features. Their guides live under Customize.
+
+## Reading and layout
+
+- [Callouts](https://www.shoalrun.com/author/components/callout.md) — notes, tips, important messages, warnings, and cautions.
+- [Badges](https://www.shoalrun.com/author/components/badge.md) — short inline labels for statuses, platforms, and versions.
+- [Keyboard shortcuts](https://www.shoalrun.com/author/components/kbd.md) — key names inside instructions.
+- [Short definitions](https://www.shoalrun.com/author/components/info-hint.md) — brief definitions that readers expand with a click, tap, or keyboard.
+- [Tooltips](https://www.shoalrun.com/author/components/tooltips.md) — supporting text shown on hover or keyboard focus.
+- [Progress](https://www.shoalrun.com/author/components/progress.md) — a bounded count with visible text and a bar.
+- [Definition lists](https://www.shoalrun.com/author/components/definition-list.md) — terms and rich explanations in semantic HTML.
+- [Action links](https://www.shoalrun.com/author/components/action-link.md) — prominent next-step and download links.
+- [Math](https://www.shoalrun.com/author/components/math.md) — inline and display LaTeX expressions rendered to MathML.
+- [File trees](https://www.shoalrun.com/author/components/file-tree.md) — nested files, folders, icons, and links.
+- [Steps](https://www.shoalrun.com/author/components/steps.md) — numbered procedures with titles and full instructions.
+- [Timelines](https://www.shoalrun.com/author/components/timeline.md) — milestone progress with a current stage and completion bar.
+- [Collapsibles](https://www.shoalrun.com/author/components/collapsible.md) — individual disclosures and compact groups for optional detail.
+- [Tabs](https://www.shoalrun.com/author/components/tabs.md) — alternate views and their child panels.
+- [Code blocks](https://www.shoalrun.com/author/components/code-blocks.md) — fenced examples, filenames, and copy behavior.
+- [Images](https://www.shoalrun.com/author/components/images.md) — responsive images, captions, width limits, and expanded viewing.
+- [Diagrams](https://www.shoalrun.com/author/components/diagrams.md) — D2 and Mermaid source rendered to SVG with Markdown source preserved.
+- [Only](https://www.shoalrun.com/author/components/only.md) — a short block for HTML or Markdown alone.
+- [Tables](https://www.shoalrun.com/author/components/tables.md) — optional row filtering and sticky headings for long tables.
+- [Walkthroughs](https://www.shoalrun.com/author/components/walkthroughs.md) — code explained step by step beside a scrolling code pane.
+- [Hero](https://www.shoalrun.com/styling/layouts.md) — a landing page opener with a title, tagline, and action buttons.
+- [Section](https://www.shoalrun.com/styling/layouts.md) — a full-width band on a splash page.
+- [ReaderSection, ReaderChoice, and ReaderFilter](https://www.shoalrun.com/author/reader-views.md) — marked sections, choice buttons, and in-page filter controls.
+- [FrontmatterReference](https://www.shoalrun.com/author/frontmatter-reference.md) — publish this project's built-in and declared page fields as a live reference.
+
+## Links and reading paths
+
+- [DocLink](https://www.shoalrun.com/author/components/doc-link.md) — a link by stable document ID.
+- [DocCard, DocCards, and DocCollection](https://www.shoalrun.com/author/components/cards.md) — document previews, curated lists, and filtered collections.
+- [CookbookChooser](https://www.shoalrun.com/author/components/cookbook-chooser.md) — choose among custodian-approved sets of prebuilt recipes.
+- [RelatedReading](https://www.shoalrun.com/author/components/related-reading.md) — authored relationships as links or cards.
+
+## Reuse and API content
+
+- [Snippet and Var](https://www.shoalrun.com/author/snippets.md) — shared content and typed values.
+- [ApiExample and ApiSchema](https://www.shoalrun.com/author/components/api-embeds.md) — named OpenAPI samples and schemas.
+- [Fields](https://www.shoalrun.com/author/components/fields.md) — authored field lists that match schema formatting.
+
+[Code highlighting](https://www.shoalrun.com/author/components/code-blocks.md) explains Shiki, theme selection, plain output, and custom adapters. Tabs and collapsibles accept ordinary Markdown and supported MDX components in their bodies; their subpages explain the exact nesting rules.
+
+## HTML, Markdown, and agents
+
+Each supported component has a defined HTML and Markdown representation. Browser controls can reveal or rearrange information, while the Markdown form exposes the content described in that component's reference. Agents can follow document links and read examples without operating those controls. Check each reference's **HTML, Markdown, and agents** section for exceptions, such as content deliberately limited to one format with `Only`.
+
+## Related reading
+
+### Read first
+
+- [Content and stable IDs](https://www.shoalrun.com/author/content.md) — Write a page with a stable ID before adding components to it.
+
+### Next steps
+
+- [Custom components](https://www.shoalrun.com/author/components/custom.md) — Register trusted components that preserve shared content.

package/agent-docs/author/content.md

@@ -0,0 +1,74 @@
+---
+id: guide.content-identity
+title: Content and stable IDs
+summary: Give each page a durable identity and publish explicit variants.
+type: explanation
+area: authoring
+subarea: authoring-pages
+canonical: /author/content
+---
+
+# Content and stable IDs
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Write documentation > Content and stable IDs
+
+**Updated: 2026-10-26.**
+
+Author pages as `.md` or `.mdx` under the content directory, `site.contentDir` (default `content`, relative to `docs.config.yaml`). The build parses and validates every `.md` and `.mdx` file there, drafts included, so a stray README without frontmatter fails the build. The `id` identifies a document independently of its filename, title, slug, and navigation position. A page's `slug` sets its public route. The compiler rejects route collisions and duplicate IDs within a publication variant.
+
+Keeping identity separate from location lets the documentation grow without reconnecting every reference. A filename is an authoring choice; a slug is a reader's address; the ID is the lasting connection used by links, navigation, and relationships. Renaming a page can leave its ID intact even when its URL needs a redirect.
+
+```yaml
+---
+id: guide.example
+title: Example guide
+summary: A short description for navigation and discovery.
+type: guide
+slug: /guides/example
+channel: production
+version: current
+access: { policy: public }
+---
+```
+
+Publication channel, API version, and language are separate axes. Published pages need channel and version, supplied on the page or through [global frontmatter](https://www.shoalrun.com/author/frontmatter.md). Language uses global frontmatter defaults/enforced values first, then `publications.defaults.language`, then `en`. An explicit page language overrides that default. Enabled publication entries can also omit language to inherit the same default; the project config declares supported combinations and route prefixes. Nonpublic pages are excluded before rendering. The prototype does not yet provide hosted role-based access control.
+
+Link to another document by ID with `[the guide](doc:guide.example)` or `<DocLink doc="guide.example">the guide</DocLink>`. These become the current route in HTML and the corresponding `.md` route in Markdown. A slug or filename change leaves ID-based links intact. Unknown IDs fail the build.
+
+The current MDX semantic adapters cover GitHub Flavored Markdown and the elements in the [component reference](https://www.shoalrun.com/author/components.md), including [diagrams](https://www.shoalrun.com/author/components/diagrams.md). Dynamic expressions and unknown components fail because they cannot yet be represented faithfully in both HTML and Markdown. See [published outputs](https://www.shoalrun.com/publish/output.md) for what an agent receives.
+
+Set the root language once, for example:
+
+```yaml
+publications:
+  defaults: { channel: production, version: current, language: fr }
+  channels:
+    production: { pathPrefix: "" }
+  versions:
+    current: { pathPrefix: "" }
+  enabled:
+    - { channel: production, version: current }
+    - { channel: production, version: current, language: de }
+```
+
+Pages without `language` use French at their ordinary route. A page with `language: de` uses the German publication and a `/de` route prefix.
+
+## Related reading
+
+### Read first
+
+- [How Shoalrun works](https://www.shoalrun.com/concepts.md) — See how IDs, slugs, and routes fit into the build.
+
+### Next steps
+
+- [Page metadata](https://www.shoalrun.com/author/frontmatter.md) — Add the metadata fields each page needs after inheritance.
+
+- [Organize site navigation](https://www.shoalrun.com/author/navigation.md) — Place the page in the site menu.
+
+### Related topics
+
+- [DocLink](https://www.shoalrun.com/author/components/doc-link.md) — Link to pages by stable ID so links survive slug changes.