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

Create a page

Create a page from a template, complete its scaffolded draft, and publish it in navigation.

Updated
Read as Markdown

Create a page from a template with scaffold. Templates prompt you for the page's frontmatter, an introduction, the main content, and related pages before you publish. This is the recommended authoring workflow for new pages.

This guide assumes you have completed getting started and are working in my-docs/. Keep SHOALRUN_CLI pointing to the checkout's framework/dist/cli.js.

Choose a template

Choose the template that matches what the reader needs to accomplish.

Template Use it for
tutorial A reliable guided exercise for learning by doing.
how-to A specific task, with practical actions and a success check.
reference Exact syntax, fields, options, examples, errors, and limits.
explanation Concepts, context, reasons, and tradeoffs.
api-reference Editorial context above generated operation details; requires one known operation ID.
recipe A complete task used by recipe and cookbook workflows.
ingredient One reusable action or check used in recipes.
cookbook A page that helps readers choose complete recipes.

These templates ship with the CLI. guide and troubleshooting remain available for compatibility. Projects can register additional templates or override built-ins.

The CLI includes a recipe template for a complete customer task, written directly or assembled from ingredients. Built-in ingredient and cookbook templates support reusable steps and workflow selection. The ingredient draft command can start one ingredient from an API example; recipe draft assembles an ordered set of ingredient files for review.

Use the project's template for the document type when one exists. Project templates can also override the built-in names. See templates to register or change one.

Scaffold the draft

From the project directory:

node "$SHOALRUN_CLI" scaffold how-to -n content/track-parcel.mdx \
  --id how-to.track-parcel --title 'Track a parcel'

The command finds docs.config.yaml, creates the file, and adds the template body and draft frontmatter. It refuses to overwrite an existing file. This example sets the stable ID and title explicitly; the CLI derives the slug /track-parcel from the target path.

Without overrides, this path would produce ID how-to.track-parcel and title Track Parcel. The generated summary starts with Draft guide for and must be replaced before publication. Publication fields come from your project configuration.

Complete the template

Open content/track-parcel.mdx and work through its prompts:

  1. Read the comments in the frontmatter, fill in the placeholder fields, and delete the comment lines.
  2. Set updated to today's date in YYYY-MM-DD format. Write an introduction of 150 words or fewer and remove irrelevant optional sections.
  3. Follow the chosen shape. Write a guided exercise, practical task actions, organized reference facts, or conceptual discussion. For this how-to, write actions and checks.
  4. Keep the HTML, Markdown, and agents section when the page uses a component or behavior that changes either output or what an agent reads. Otherwise delete it.
  5. Add relationships for the page, or delete Related reading. Verify technical claims before you publish.

Replace every TODO prompt enclosed in double square brackets. Adapt the sections to the task rather than leaving irrelevant prompts behind. Templates provide a starting structure; editing a template later does not rewrite this page. The quickstart shows a completed example.

Keep the generated access.policy: draft while writing. Drafts are validated but omitted from the published site, even if the starter defaults to public access. Headings in the body begin at level 2 because Shoalrun renders the page title separately.

Publish the page

After reviewing the content, change the generated access value to:

access: { policy: public }

Keep the ID how-to.track-parcel and slug /track-parcel for this example. Check the channel, version, and language match an enabled publication. The build rejects public pages with unresolved template prompts or the generated draft summary. See page metadata for shared defaults and publication rules. The generated frontmatter reference lists native fields and this site's project declarations.

Put it in navigation

Append this item to the existing navigation list in docs.config.yaml:

  - id: track-parcel
    doc: how-to.track-parcel

Use the page's frontmatter ID for doc; the navigation item's own id identifies that menu entry. You can nest the item under a group's items list instead. Navigation uses the page title as its label unless you supply label.

A public page can have a working URL without appearing in the sidebar. Adding this entry makes it discoverable there. See organize navigation for groups, includes, and links.

Verify HTML and Markdown

From the project directory:

node "$SHOALRUN_CLI" build docs.config.yaml site-dist
node "$SHOALRUN_CLI" serve site-dist --port 8765

Open http://127.0.0.1:8765/track-parcel and confirm that the page appears in navigation and that its links work. Then open http://127.0.0.1:8765/track-parcel.md and confirm that the same prose is available and internal links point to Markdown pages. Press Ctrl+C to stop the server.

If you use another publication or a language prefix, inspect the built documents.json for the resolved URLs. To preview edits continuously, use node "$SHOALRUN_CLI" dev docs.config.yaml site-dist --port 8765.

Next, organize your navigation as the site grows.

Next steps

  • Templates — Adapt the starting template for your team's next pages.

Reference while working

  • Page metadata — Check the scaffolded page's publication and metadata fields.