Shoalrun documentation frameworkMenu
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

Site and theme settings

Configure the site identity, header, footer, agent guidance, colors, and fonts.

Updated
Read as Markdown

Configure the site identity, header, footer, agent guidance, colors, and fonts. These keys belong in docs.config.yaml or an included configuration file. For file composition and validation commands, see Configure your project. Use the configuration index to find another setting.

site

Required.

Key Default Meaning
title None Site name in the masthead and the heading of /llms.txt.
contentDir content Page directory, relative to the root config file. Every .md and .mdx file in it is read.
contentFilter None Build-time whole-page selection by configured reader facets. All selected facets must match; any listed choice within a facet matches. Unmarked pages are excluded. Unknown or empty selectors and selections with no pages fail. See separate sites from shared content.
basePath "" Mount point for public pages and resources, such as /docs. Use URL path segments without escapes or dot segments. Build tools keep internal manifests at the output root; the public site is also complete inside the docs/ output subtree.
origin None The site's HTTPS origin, such as https://docs.example.com, with no path or trailing slash. Required to publish the API catalog, and makes link-preview URLs absolute.
indexing true Set false on previews to add noindex to pages, disallow crawling in robots.txt, and omit the XML sitemap.
updated None Optional YYYY-MM-DD fallback for sitemap lastmod, especially on generated API pages. Page updated overrides it.
favicon A mark drawn from the preset and palette A local .svg or .png file. See share images and favicon.
customCss None A local .css file linked after the framework styles. See CSS.
editionBadge auto Masthead publication label: auto shows only the channel, version, or language values that differ across publications; always or never.
header.links None Masthead links. See header.
agentDiscovery Visually hidden until focused HTML agent guidance, visual presentation, and link labels. See site.agentDiscovery below.
footer None Footer columns, bottom-row links, and a text line. See site footer.

A minimal site needs only a title:

docs.config.yaml
site:
  title: Payments documentation

Keep pages in another directory, add a stylesheet, and always show the publication label:

docs.config.yaml
site:
  title: Payments documentation
  contentDir: pages
  customCss: ./styles/project.css
  editionBadge: always

Publish the API catalog. origin is required once any API sets discovery.endpoint:

docs.config.yaml
site:
  title: Payments documentation
  origin: https://docs.example.com

Add masthead links:

docs.config.yaml
site:
  title: Payments documentation
  header:
    links:
      - { label: Guides, href: /start }
      - { label: GitHub, href: "https://github.com/example/payments", style: button }
      - { label: Sign up, href: "https://example.com/signup", style: primary }

Add a footer:

docs.config.yaml
site:
  title: Payments documentation
  footer:
    columns:
      - title: Guides
        links:
          - { label: Get started, href: /start }
    links:
      - { label: Privacy, href: /legal/privacy }
    text: © 2026 Example, Inc.

site.agentDiscovery

Optional mapping. It controls the early agent guidance in HTML pages.

Key Default Meaning
mode focus Controls visual presentation and whether the block is included. See the visual and agent behavior below.
label For agents Nonempty plain text before the message and links. Shoalrun adds the colon.
message None Optional plain-text guidance. HTML tags are escaped; Markdown syntax stays literal.
links.article Skip to article Label for the generated #main link.
links.index Documentation index Label for the generated /llms.txt link, including site.basePath.
links.markdown Read this page as Markdown Label for the current page's Markdown twin.
docs.config.yaml
site:
  title: Payments documentation
  agentDiscovery:
    mode: visible
    label: For agents
    message: Use the Markdown version for complete examples and nested schemas.
    links:
      article: Jump to the article
      index: Browse all documentation
      markdown: Read Markdown

Only link labels are configurable; Shoalrun generates their destinations for each page. Labels must be nonempty strings. Unknown keys and invalid mode values fail validation and builds.

The mode controls visual presentation and whether the instruction is included:

Value Visual presentation Agent reading HTML
focus Visually hidden until a link receives keyboard focus. The instruction and links are present in the HTML.
visible Always shown as a banner. The same instruction and links are present in the HTML.
disclosure A compact header toggle, closed initially. Links remain in HTML source; open it for visual navigation.
off No agent guidance block appears. The instruction and its links are omitted from the HTML.

Screen readers and agents parsing raw HTML can encounter the block in all enabled modes. An agent using screenshots sees the same visual presentation as a human. Some HTML extraction tools discard visually hidden elements; the document head also provides discovery links. Visually hiding the block does not make it private.

This setting affects HTML only. It does not change the Markdown index link, generated discovery files, or the standard accessibility skip link. The focus and visible blocks follow that skip link before the header. Disclosure mode places the toggle inside the header. It is hidden in print.

Content freshness

site.freshness: { history: ./config/content-updates.json } opts into persistent content-digest dates. Paths resolve from the root config directory and must stay inside the project. The first build seeds declared dates; changed content later receives today's UTC date while unchanged content retains its date. Commit the history file for reproducible clean builds. Without this setting, declared updated and site.updated remain authoritative. Native page verified is an independent, author-set calendar date. See revision and verification dates.

theme

Accepts preset, palette, mode, toggle, and fonts. See themes, palettes, and color modes. The build checks palette colors for WCAG contrast.

Key Default Values
preset shoal shoal, reef, ledger, vice
palette The preset's palette kelp, coral, ink, harbor, amethyst, vice, or a custom mapping
mode light light, dark, system
toggle true with mode: system, otherwise false true or false. true is allowed only with mode: system.
fonts The preset's bundled fonts system, or a mapping of body, headings, and code. See Fonts in themes.

Change the layout and keep its colors:

docs.config.yaml
theme:
  preset: ledger

Follow the reader's system setting and let them switch:

docs.config.yaml
theme:
  preset: reef
  palette: harbor
  mode: system

Use a built-in palette as a base and change the brand colors:

docs.config.yaml
theme:
  palette:
    extends: harbor
    light: { accent: "#0a6a48", link: "#0a6a48" }
    dark: { accent: "#4fd6a4", link: "#7fe0bd" }

Use dark mode only, without a switch:

docs.config.yaml
theme:
  mode: dark

Read first

Reference while working