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

Themes

Pick a site shape, pair it with a color palette, and choose how light and dark mode behave.

Updated
Read as Markdown

The theme setting controls how the HTML site looks. It has five keys, and each has a default:

docs.config.yaml
theme:
  preset: reef      # site shape
  palette: harbor   # colors
  mode: system      # light, dark, or system
  toggle: true      # reader switch for light and dark mode
  fonts: system     # optional: turn off the preset's bundled fonts

Omit theme to keep the default: the shoal preset, the kelp palette, the preset's fonts, and light mode only. An unknown value fails the build.

To see every combination on a real page, open Try a theme.

Start with a preset. Change the palette if its colors don't fit your brand. Set the mode if readers need dark mode. Use project CSS for anything else.

Presets

A preset sets the shape of the site. It controls layout, corner radii, and type, and how panels, navigation, and cards look. Each preset has a default palette. Any palette works with any preset.

Preset Shape Default palette
shoal Flat page with a ruled sidebar and square-cornered controls. kelp
reef Rounded panels float on a tinted page. Navigation items and controls are pills. coral
ledger A technical manual with an inked masthead, serif body text, monospace headings, numbered sections, and hard-edged cards. ink
vice A night masthead with a sunset stripe, bold italic display type, neon section rules, and cards that glow on hover. vice

Presets change CSS only. Page markup, URLs, and Markdown twins stay the same.

Fonts

Each preset ships its own fonts, so the site looks the same on every operating system:

Preset Body Headings Code
shoal Inter Inter System monospace
reef Figtree Figtree System monospace
ledger Source Serif 4 JetBrains Mono JetBrains Mono
vice Figtree Jost System monospace

The fonts are Latin variable fonts under the SIL Open Font License. The build copies them to /assets/fonts/ with their license files. A browser downloads only the faces a page uses, and the page preloads its body font. Characters outside the Latin set use the system fallback. Until a font arrives, the page uses a local font resized to match it. Text doesn't shift when the bundled font loads. Agents read the Markdown twins, which load no fonts.

To use system fonts only, set fonts: system. Each preset then falls back to its system font stack.

Use your own fonts

Set any of body, headings, and code. A role you leave out keeps the preset's font. headings defaults to the body font.

docs.config.yaml
theme:
  preset: reef
  fonts:
    body:
      family: Acme Sans
      files:
        - ./fonts/AcmeSans.woff2
        - { file: ./fonts/AcmeSans-Italic.woff2, style: italic }
    headings: Acme Display
    code:
      family: Berkeley Mono
      files: [./fonts/BerkeleyMono.woff2]
  • family is the name CSS uses. A plain string, such as headings: Acme Display, names a font without shipping files. Use it for a font that project CSS loads, or one installed on readers' machines.
  • files lists local .woff2, .woff, .ttf, or .otf files, relative to the config file that declares them. The build copies them to /assets/fonts/project/. File names can use letters, numbers, dots, dashes, and underscores, and two files can't share a name.
  • Each file can set style (normal or italic) and weight, such as 400 or "100 900". The default weight, "100 900", suits variable fonts; give each static file its own weight.

A missing file, an unsupported format, or an unknown key fails the build. Check that your font license allows web embedding.

Fonts set here become the --font-body, --font-heading, and --font-code CSS tokens, each followed by a system fallback.

Load order

The HTML page links stylesheets in this order. Later files override earlier ones.

  1. /assets/site.css, which imports the base tokens and header styles.
    • /assets/theme-preview.css follows it, on pages that use the theme previewer.
  2. /assets/theme.css, for a preset other than shoal.
  3. /assets/palette.css, generated for any palette or mode other than kelp in light mode.
  4. /assets/fonts.css, generated from theme.fonts, unless it's system and sets nothing.
  5. /assets/project.css, from site.customCss.

When a site uses a non-default preset, palette, or mode, the html element carries data-theme and data-palette. The ledger and vice presets also set data-masthead="inked", which switches header tools to light text on a dark masthead. Project CSS can target one combination:

styles/project.css
[data-theme="ledger"] .page-head h1 { letter-spacing: 0; }

Next steps

Go deeper

  • Try a theme — Preview every preset, palette, and color mode on a live page.