yet another doc generator

September 30, 2026

Hi, long time no talk. I was busy writing a whole book, and then I took a few days off after releasing that before I got literally POSSESSED by an idea and have moved heaven and earth to bring it to fruition -- Shoalrun.

There's no such thing as a perfect doc tool, but I have a lot of opinions and undirected rage (and curiosity) about doc-building tools in general. I built my first documentation generator back in 2015. It was based on Jekyll and relied heavily (probably too heavily) on general templating and... you guessed it... page metadata.

Shoalrun is a combination art project, portfolio piece, and laboratory where I get to push the limit of what I think content and content tooling should be, at least in whatever domain I currently work from.

I had a lot of sources of inspiration (both negative and positive) from my years as a tech writer and tooling lover. I wanted to build something maximally flexible that also could keep things on the rails. I wanted something that uses frontmatter for deterministic features that feel like AI. I also wanted to play with what a BYO search and chat hookup could look like. And also leave room for others to use as much AI as they want.

One of the problems I really wanted to chew on was how to give both AI and human readers content in a form that works best and prevents cognitive (and maybe contextual???) overload (no, I'm not saying I believe AI has true cognition, just stick with me here okay). I want to build flashy interactive components that give humans a better chance of understanding a concept, but I also want to give agents any useful information without the extra junk, but WITHOUT doing any extra work.

I centered the design with this project around making everything for two audiences: humans and agents. Not one above the other because it's honestly trivial to give them both what they need.

I guess the more polished marketing-friendly summary is:

One source can serve different readers without fuss. Shoalrun lets authors shape the browser experience, choose what enters agent-facing Markdown, and add content for one format when the two readers need different explanations. The framework also provides settings and extension points for the rest of a documentation site.

What makes Shoalrun special

What interests me most is the interconnectedness that comes from treating information as a first-class object. Each doc has its own identity, metadata, and relationships. Its stable ID connects links, navigation, cards, and related reading, so I can move the source file without breaking those connections. See how Shoalrun works.

I want config to be composable, too. I can keep navigation, API sources, templates, and other settings in small YAML files, combine them with includes and presets, and trace which file supplied a value. The project can grow without forcing every concern into one config file. See configuration composition.

Presenting and linking content for humans and agents are first-class features. A rich component has an explicit form in both the browser and the page's Markdown twin. The build can turn one accepted source into interactive HTML, agent-readable Markdown, /llms.txt, and a document manifest. It rejects unsupported dynamic MDX instead of silently dropping content. Authors can still write a section for just one output when that reader needs a different explanation. See agent-friendly output.

This structure also makes workflows easier to connect. An ingredient can be reused in a complete recipe, and a cookbook can assemble the reviewed recipes a reader selects into one path. See recipes and cookbooks.

API content follows the same approach. Local OpenAPI files can supply reference pages, examples, and focused contracts for individual operations. A public build requires a review digest for imported API content, so a changed source returns to review before publication. See API review.

I'm building Shoalrun because I will never be fully satisfied with any mass market tool for docs because docs are never a one-size-fits-all thing, on any level. I want to see what I can do.

As for project's current status and future -- right now, only the docs/prototype are public. The compiler and all the guts are still a private prototype because I'm not totally sure if I want yet another open source doc generator out in the world.