Shoalrun is a private prototype for publishing documentation for people and agents from the same source. This public site is built with it. The compiler and CLI are available as an invite-only alpha package; there is no public package release.
What works today
-
One source, two reading formats. Markdown and supported MDX components produce a browser site and a Markdown copy of every page. Generated indexes, manifests, and section resources help agents discover and read the content without running the site’s JavaScript.
-
Structured authoring. Templates, reusable snippets, custom metadata, and composable configuration support guides and reference pages. Stable page IDs connect links, cards, navigation, and related reading. Recipes and cookbooks combine reusable instructions into complete workflows. Agent authoring tools provide project discovery, source context, draft previews, and local validation for your existing coding agent.
-
Rich documentation pages. Built-in components include tabs, callouts, tables, code walkthroughs, steps, timelines, and API embeds, with defined Markdown output. Diagrams render D2 and Mermaid syntax as SVG during the build; Pele renders the Mermaid diagrams. Markdown retains the diagram source and explanation.
-
Reader controls. File trees have expandable folders and keyboard navigation. Collapsible groups join related disclosures without gaps. Authors can synchronize related tabs and add captions or expanded viewing to images.
-
Configurable sites. Themes, palettes, layouts, headers, and footers shape the presentation. Navigation tabs organize larger sites into sections. Explicit versions and languages publish separate page variants, while reader views tailor navigation and marked content to different audiences.
-
API documentation. OpenAPI sources supply reference pages, named examples, request samples, and contracts for individual operations. Authors can combine generated references with guides and review imported API content before publishing it.
-
Search and documentation tools. Built-in search works in the browser without a model key. Optional semantic search and cited answers use your configured providers. Read-only Model Context Protocol (MCP) tools let agents search and read pages or sections. They run through a local stdio process or a public HTTP endpoint on Node or Vercel.
-
Publishing and measurement. Local previews and checks support static publishing, with Node and Vercel serving options. Optional browser analytics and HTTP MCP analytics send events through adapters to your chosen service. Both are off by default; their guides describe the event fields, filtering, and configuration.
-
Experimental visual navigation. Explore the docs offers circles, expandable branches, arcs, a relationship matrix, and a force layout. The views use declared page categories and reading relationships, including authored explanations. Agents can read the same metadata and relationships through the document manifest without running the visualization.
What I want to add next
- Improve visual navigation. Refine layout sizing, label collisions, dense graph views, filtering, relationship explanations, and accessibility as we try the experimental explorer on larger documentation sets.
- Custom access control. Add connectors for customers’ own role-based access control (RBAC) systems, with consistent access decisions across HTML, Markdown, search, downloads, and MCP.
These are intended additions, without a promised release date or a commitment to public package or source distribution.
Current limits
- Prototype stability. Configuration, extension points, and output formats can still change. There is no stable release or compatibility promise yet.
- Component extensibility. Trusted custom components lower into shared content, with a portable authoring skill. Arbitrary executable MDX remains unsupported. Project CSS, browser modules, and configured build extensions are trusted project code.
- API coverage. OpenAPI and JSON Schema support is partial; check the support reference against your source. Request examples are copyable, but Shoalrun does not provide a live API explorer that sends requests.
- Private content. Reader views do not restrict access to published files. Shoalrun has no built-in reader authentication, and its HTTP MCP endpoint currently serves one selected public publication. Host-level authorization is a separate responsibility.
- Managed services. Shoalrun does not provide managed hosting, translation, or chat. Versions and translations need explicit authored variants. Optional model and analytics services need your own configuration and accounts.
Automatic skill generation and general agent orchestration are deliberate non-goals. Authors remain responsible for the accuracy and usefulness of their documentation.