Docs for people. Context for agents.

Readable output, with checks you can inspect

Write Markdown, MDX, and OpenAPI once. People get tabs, disclosures, navigation, and reader views. Agents get the supported content in reading order, with stable page identities and machine-readable contracts.

A tabbed page, without missing panels

This example has two client choices and a closed disclosure. The Markdown includes both clients and the troubleshooting detail.

<Tabs label="Client">
<Tab label="curl">

```sh
curl -fsS https://api.example.com/health
```

</Tab>
<Tab label="JavaScript">

```js
const response = await fetch('https://api.example.com/health');
console.log(response.status);
```

</Tab>
</Tabs>

<Collapsible title="If the request fails">
Check the service URL and your network connection.
</Collapsible>

curl -fsS https://api.example.com/health

const response = await fetch('https://api.example.com/health');
console.log(response.status);

### curl

```sh
curl -fsS https://api.example.com/health
```

### JavaScript

```js
const response = await fetch('https://api.example.com/health');
console.log(response.status);
```

### If the request fails

Check the service URL and your network connection.

Fetch the published output

Start with the compact page list, choose a page, and fetch its Markdown. The full manifest supplies byte digests when you need verification; build information and sync snapshots let returning clients detect changes. Try the example on the agent-friendly guide to compare live components with tested Markdown output.

curl -fsSL https://www.shoalrun.com/llms.min.txt
curl -fsSL https://www.shoalrun.com/publish/agent-friendliness.md

Hosts that support content negotiation can serve the same Markdown at the HTML route when the request sends Accept: text/markdown:

curl -fsSL -H 'Accept: text/markdown' https://www.shoalrun.com/author/search

Check both audiences before you publish

Shoalrun builds static files for your host. Its audit builds HTML and Markdown, checks links and API contracts, and runs configured project tests. An unsupported component stops the build instead of disappearing from the agent's document.

For example, adding <UnknownWidget /> to a page makes shoalrun check fail with the source path:

FAIL build
  …/docs.config.yaml: …/content/welcome.mdx: <UnknownWidget> has no semantic/Markdown adapter
Checks failed. Fix the findings above and rerun shoalrun check.

This is illustrative output, not a failure on the current site. The check catches unsupported representations; it does not establish that every sentence is correct.

Eval reports let you add reviewed task results to the publishing gate. Required failures and reports from an older build fail the audit. You supply the agent run and answer review. Shoalrun's five example tasks are a self-reviewed demonstration, with prior context; they are not an independent measure of agent accuracy or a comparison with other platforms.

• Audit a docs project

  Run project tests and local API representation checks with one CI command.

• Evaluate agent tasks against your docs

  Define realistic tasks, record reviewed answers from your own agent, and check the results against a documentation build.

• Add an OpenAPI API

  Import a local OpenAPI file, author an operation page, review its public content, and build HTML and Markdown.

Control the reading experience

Reader views use the readerFilters configuration to shape browser navigation, search, cards, and marked sections. A UI reader can follow screen actions while a developer sees request examples. The published Markdown retains every reader-marked section with a label.

Reader views are visibility controls, not access controls. Hidden browser content remains in published files. Use access.policy to exclude pages from a public build and host authorization to protect private content.

Format-specific content lets you replace an interactive instruction with a useful written explanation. Markdown metadata settings choose which frontmatter fields are published for agents. These are authoring and publication choices; discovery files do not protect private data.

• Reader views

  Reader-view configuration, page and section marks, controls, and agent-facing behavior.

• Content for one format

  Use Only to add content to the HTML page or its Markdown twin alone.

• Markdown metadata

  Public field projection, source paths, profiles, precedence, and required values.

Make it look like yours

Choose a theme and palette, follow the reader's light or dark setting, and customize brand colors or CSS. The build checks configured palette colors for contrast.

theme:
  preset: reef
  palette: harbor
  mode: system

theme:
  preset: vice
  palette: harbor
  mode: system

Explore themes or customize the CSS.

Bring your own tools

Customize these parts through config, local modules, or a host adapter.

Split config across files with $include, share a base with extends, and ask shoalrun config explain which file set a value.

Give your coding agent the docs

The prototype bundles four authoring skills: setup, authoring, recipes, and code walkthroughs. It also includes Shoalrun's generated documentation for offline lookup:

shoalrun docs search "custom search provider"
shoalrun docs read guide.search

Use the bundled skills or consult the command reference. Shoalrun does not generate reader-side skills for each site it builds. Skills need human expertise to create and maintain; see the non-goals.

• Organize project configuration

  Learn how Shoalrun resolves config files, layers presets, tracks path origins, and applies page defaults before building publications.

• Configuration reference

  Every top-level setting in docs.config.yaml, with defaults, validation rules, and links to the full guides.

• Deploy your documentation

  Build your site, choose Vercel or Node hosting, and verify the deployed HTML and Markdown.