Shoalrun documentation frameworkMenu
For agents
Start with https://www.shoalrun.com/llms.txt for the documentation index, then read the Markdown pages it links. Skip to article. Documentation index. Read this page as Markdown.
Changelog entry

Content delivery, verification dates, and clearer references

Reuse documentation through static bundles or REST, display technical verification dates, and find clearer API and layout guidance.

Version 0.1.0-alpha.13
Read as Markdown

Alpha.13 makes documentation reusable by applications, agents, services, and publishing workflows. It adds section and snippet exports, clients for static and REST delivery, native API response-header references, and visible technical verification dates.

Upgrade to CLI 0.1.0-alpha.13 and rebuild your site and content exports. Custom export consumers need the manifest migration below. This entry also covers the accompanying documentation improvements.

Deliver selected content

Content delivery extends whole-page export to individual sections and named snippet instances. A product can show billing instructions beside its settings; an agent can retrieve a procedure; a publishing workflow can reuse content in training material.

The browser-safe client reads HTML or Markdown from a static bundle. Its mount helper rewrites IDs and links so the same content can appear more than once in an application. The REST adapter serves the same snapshots through resource lists, metadata, and representation endpoints. Both clients use the same snapshot interface.

Section IDs derive from headings by default. An optional trailing <Anchor id="refunds" /> preserves a reference when its heading changes. Before exporting a section alone, review it without the rest of the page and record that judgment in standaloneSections.

Compare releases with --previous-manifest and reject removed references with --fail-on-removed. Keep complete revisions under immutable paths when applications remain open during updates. Authentication, search, editing, and production hosting remain host responsibilities.

Migrate an export consumer

Existing documents selectors remain shorthand for whole pages. The exported manifest now uses typed resources:

  • Read manifest.resources instead of manifest.documents.
  • Identify a page with ref.kind: page and ref.documentId instead of a document's id.
  • Follow resource links through their typed ref objects.
  • Read representation paths from the rebuilt manifest instead of retaining old filenames.

See export migration and the manifest reference. The package includes a content-delivery example for static and REST clients, plus an updated help-drawer example for whole pages.

Read complete API references and examples

Native API references now render schema-based OpenAPI response headers with descriptions, constraints, and examples. These contracts previously stopped the build. Content-style headers and response links still require adaptation.

Generated request samples handle HEAD responses without trying to read a response body. JavaScript, Node.js, and Python samples distinguish JSON from text responses. The content HTTP API reference uses the native operation format and includes all six GET and HEAD operations.

Distinguish revision from verification

An authored verified date now appears as a labeled semantic <time> element in the standard HTML page header. It remains separate from updated: revision records content changes; verification records a check of technical claims. Markdown and documents.json retain the same dates. Builds never assign verification dates.

Set showVerified: false on a page, or in frontmatter.defaults, to hide verification in HTML only. A page can override the shared default. See verification dates.

Find the right authoring guidance

The documentation now separates content-delivery tasks, client reference, manifest reference, and HTTP operations. Section guidance explains what a standalone declaration means before introducing its syntax, with a concrete missing-context example.

The layout guide distinguishes giving content more room with layout: wide from hiding the outline with tocDepth: 0. Page metadata links to that choice, and task wording improves discovery for outline-related searches. These updates are included in the bundled documentation used by CLI and MCP tools.

Feature availability follows one convention: “Available since VERSION.” Templates and authoring guidance require an exact assigned version rather than a guessed release number.

The navigation heading above the sidebar filter can be hidden or renamed with outputs.html.navigation.heading. Set it to false to remove “Explore”; the filter keeps its accessible label.

Clicking article content no longer draws a rectangle around the entire page body. Keyboard jumps still focus the article, with a visible indicator at its title. Focus indicators on links, buttons, and inputs remain available.

Preserve teaching examples and discover native relationships

Fenced code blocks can contain literal scaffold TODO examples without failing publication. Those examples remain readable in HTML and Markdown. Unresolved prompts in prose or frontmatter still fail the public build.

Project discovery and validation now suggest native relationships when a related-reading or related-material section contains document links. The hint is nonblocking and does not generate relationships. Authors still choose the purpose and reason for each connection. The component index also maps reader tasks to native features.

HTML, Markdown, and agents

Content exports contain passive HTML or readable Markdown, without website controls. Applications own rendering and interaction; agents can read typed references and retrieve Markdown without operating a browser. HTML visibility settings such as showVerified do not remove the underlying verification date from Markdown or the manifest.