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.
Reference

CookbookChooser

Let readers select reviewed recipes and assemble them into one reading path.

Updated
Read as Markdown

Use <CookbookChooser> to help a reader choose a complete recipe or combine compatible recipes. The author reviews each recipe and sets its place in the choice list. The browser loads the selected published recipe pages and displays their instructions. The component does not read ingredient files, generate a recipe, or execute commands. Start with how recipes and cookbooks work, then configure a cookbook; this page lists the component's exact syntax.

Syntax

Map each option to a public recipe in project YAML, then place the chooser on a page in the same publication:

config/cookbooks.yaml
site-checks:
  title: How much validation do you need?
  mode: single
  options:
    - { id: build, label: Build, doc: recipe.build-docs }
    - { id: audit, label: Audit, doc: recipe.audit-docs }
docs.config.yaml
cookbooks: { $include: ./config/cookbooks.yaml }

<CookbookChooser id="site-checks" />

Try the live chooser for this documentation project:

Recipes in this cookbook:

Value Rule
id Required literal cookbook ID from cookbooks. No child content or other attributes.
options Nonempty ordered list of unique lowercase IDs, visible labels, and recipe document IDs. This order controls the assembled path.
mode Optional single for alternatives or multiple (default) for compatible recipes.
Option descriptions Optional when, needs, and outcome explain the choice in HTML and Markdown. Each is nonempty plain text.
Recipe target Must be a public type: recipe page in the chooser's channel, version, and language.

The build rejects duplicate IDs, labels, or recipe targets, plus missing, draft, wrong-type, or wrong-publication targets.

HTML, Markdown, and agents

HTML displays checkboxes, or radio buttons for mode: single, after the page script starts. Selecting options loads the published recipe pages and assembles their instructions in configured order under Your path. Each section links to its source recipe. If a page cannot load, the source link remains available. The recipe list below the controls works without JavaScript.

The cookbook page and choice list are compiled at build time. Recipe content is fetched when a reader selects it in the browser. The selected option IDs are stored in the page URL. Link to this path preserves that selection; Download Markdown saves all selected recipe instructions, and Print this path prints the loaded path. Downloads fail as a whole if a recipe cannot be fetched. Printing is disabled while any selected recipe failed to load.

Markdown lists every recipe with its choice descriptions and a link to its .md page in the same order. An agent can choose a recipe from those descriptions and read its complete Markdown. The cookbook Markdown does not contain the browser-selected recipe bodies. Give an agent the recipe Markdown or downloaded selection to follow a task. A selection URL does not create a published Markdown endpoint.