Shoalrun documentation framework
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.
How to

Add Shoalrun to another build or host

Publish compiled files alongside another site and supply the host's HTTP rules.

Updated
Read as Markdown

Shoalrun builds a complete static site without a host framework. To include its pages in another build system, run Shoalrun's CLI as a build step. Then copy the generated files into the host's output. The host does not need to parse Shoalrun's MDX or OpenAPI sources.

shoalrun build docs.config.yaml ./shoalrun-dist

The command replaces ./shoalrun-dist on each build. Use a dedicated output directory. With an empty site.basePath, copy its contents to the root of the host's published output. For a site mounted at /docs, set site.basePath: /docs and copy the public shoalrun-dist/docs/ subtree to the host's /docs mount. The build also keeps internal manifests at the output root for local commands.

Add a build adapter

An adapter for Astro, another site builder, or a deployment platform can follow these steps:

  1. Run shoalrun build <config> <temporary-output> after the host has generated its own files.
  2. Enumerate both output trees and fail if a Shoalrun file would replace a host file. Also fail if a file occupies a directory the other tree needs. Compare paths without regard to case so a build that works on one filesystem does not overwrite files on another.
  3. Copy the Shoalrun files into the host output, keeping their paths. Do not modify the generated HTML or Markdown: both came from the same content build.
  4. Configure the host's routing and response headers as described below. Run the post-deploy checker against the published URL.

The generated documents.json lists every page's HTML and Markdown URLs. redirects.json records redirects, and resource-headers.json records content types for Markdown and discovery resources. It also records Content-Security-Policy: sandbox and X-Content-Type-Options: nosniff for generated and local SVG files. Apply those headers when hosting SVGs; the Node server and Vercel adapter do this automatically. /llms.txt, search-index.json, API contracts, images, styles, and scripts are ordinary output files. The output guide lists their paths.

Supply HTTP behavior

Copying files does not make a static host negotiate Markdown at an HTML URL or apply redirects and special content types. Use the content negotiation contract to configure those rules. A host that cannot inspect request headers can still serve the direct .md URLs, but cannot provide the negotiated response. Shoalrun's Node server handles these rules; the Vercel build generates a deployable configuration for that host.

Keep the adapter small: Shoalrun owns content compilation and the generated files, while the host owns request handling. A JavaScript plugin API is not required to call the CLI or publish its output.

Next steps