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

Getting started

Create a documentation site, scaffold your first page from a template, and preview its HTML and Markdown.

Updated
Read as Markdown

This quickstart takes you from installing Shoalrun to your own working documentation site. You will scaffold a page from a template, complete its draft, put it in the sidebar, and read its HTML and Markdown output.

Private alpha: Your GitHub account needs access to the private @shoalrun/cli package. You do not need access to the framework source repository.

Prerequisites

Install Node.js 22.12 or newer and npm. Use the npm that comes with Node.js; Shoalrun sets no separate npm version. The commands below use a POSIX shell, such as Bash or Zsh.

Authenticate to GitHub Packages with a classic personal access token that has read:packages. Enter it at the password prompt; keep it out of files you commit:

npm login --scope=@shoalrun --registry=https://npm.pkg.github.com --auth-type=legacy

Your account also needs permission to read the package. A token scope alone does not grant package access.

Start your own project

Install an exact version of the private alpha and initialize the minimal starter:

mkdir my-docs
cd my-docs
npm init -y
npm install --save-exact @shoalrun/cli@0.1.0-alpha.2 --@shoalrun:registry=https://npm.pkg.github.com
npx --no-install shoalrun init .

Diagrams build without Chrome. The starter puts docs.config.yaml and content/ in your project. Initialization refuses to overwrite starter files, and preserves unrelated files such as the package manifest and lockfile.

Preview the starter:

npx --no-install shoalrun dev docs.config.yaml site-dist --port 8765

Open http://127.0.0.1:8765/. You should see the Acme handbook example with a welcome page and an installation page. Press Ctrl+C to stop the preview before continuing.

Create a page

Start new pages from a template. From the same my-docs/ directory, scaffold the built-in how-to template:

npx --no-install shoalrun scaffold how-to -n content/first-page.mdx \
  --id guide.first-page --title 'Your first page'

The command creates draft frontmatter and a body with prompts for outcomes, steps, checks, and recovery. It derives the slug /first-page and refuses to overwrite existing files. Use a registered project template when your team has one; create a page explains the choices.

Open content/first-page.mdx. Set updated to today's date in YYYY-MM-DD format. Replace its generated summary with Find the installation guide and check its Markdown page. Keep access.policy set to draft while completing the prompts.

For this small walkthrough, replace the template body below the closing frontmatter delimiter with this completed example. It keeps the introduction, actions, and verification together:

Completed template body
Find this handbook's installation instructions and their Markdown copy.
This page is for readers exploring the example documentation site.

## Before you begin

Run the local documentation preview and open its home page.
No account or credentials are needed.

## Complete the task

1. Open Setup in the sidebar.
2. Choose Install Acme to open the [installation guide](doc:guide.install).
3. Read the example version command. Acme is fictional; do not run it.

## Check the result

The installation page shows an example command: `acme --version`.
Open `/install.md` on the same local server and find that command there too.

## Handle common failures

If the page does not load, restart the preview and check its printed address.
If the installation page is missing, restore the minimal starter's install file.

## How it works for agents

The Markdown page contains the same instructions and version command.
Its installation link points to `/install.md`.

## Next steps

Read the [installation guide](doc:guide.install) in either format.

## Editorial evidence

The minimal starter's `content/install.mdx` supplies the page and example command.

Review the content and replace every remaining template prompt before setting access: { policy: public } in the header. The build rejects unfinished public drafts, including the generated draft summary.

id is the stable target used by navigation and doc: links. slug sets the page URL. Keep the generated publication fields; the minimal starter enables their combination.

Add the page to navigation

In docs.config.yaml, replace the existing navigation block with this block. Keep the rest of the file:

docs.config.yaml
navigation:
  - id: welcome
    doc: guide.welcome
  - id: setup
    label: Setup
    items:
      - id: install
        doc: guide.install
      - id: first-page
        doc: guide.first-page

Creating a page does not add it to navigation automatically. This entry puts Your first page under Setup, using its frontmatter title as the label.

Build and check both outputs

Validate the configuration, build the site, and serve it:

npx --no-install shoalrun config validate docs.config.yaml
npx --no-install shoalrun build docs.config.yaml site-dist
npx --no-install shoalrun serve site-dist --port 8765

Check these URLs in your browser:

  • http://127.0.0.1:8765/first-page: the HTML page, with Your first page in the sidebar.
  • http://127.0.0.1:8765/first-page.md: the same content as Markdown.

The installation link should take you to /install in HTML and /install.md in the Markdown output. Commands print JSON and return a nonzero exit code on failure. If a page is missing, check its publication fields and navigation entry.

Press Ctrl+C to stop the server. For ongoing writing, run the dev command again; it rebuilds and refreshes the browser when you save edits. Builds replace the whole output directory, so keep site-dist/ separate from your source files. Add site-dist/ and .shoalrun/ to your project's .gitignore if you do not want to track generated files.

Make it yours

Change site.title in docs.config.yaml, replace the Acme example content, and keep adding pages with the add a page guide. The configuration guide explains how to compose project settings. The page metadata guide explains drafts and shared defaults. For help from an agent, see use the bundled agent skills.

Continue by adding an OpenAPI API, or publish your site.

Build this site

Shoalrun's documentation repository installs the package too. From that repository's root, run npm ci and npm run docs:dev. It serves these docs at http://127.0.0.1:8770/.

Check writing style

For checks on your own built site, see audit documentation.

Next steps

  • Create a page — Create another page and add it to navigation.

Reference while working

  • CLI reference — Look up each command's arguments, defaults, and failure cases.
  • Example configs — Start from a complete config for a common kind of site.
  • Glossary — Look up a term a guide uses before you know it.