@shoalrun/cli 0.0.0-stage → 0.1.0-alpha.11

package/agent-docs/styling/layouts.sections/control-navigation-tabs.md

@@ -0,0 +1,51 @@
+---
+id: guide.layouts
+title: Page layouts, landing pages, and splash pages
+summary: Configure wide, landing, and splash pages with Hero and Sections.
+type: reference
+area: appearance
+subarea: appearance-layouts
+canonical: /styling/layouts
+---
+
+# Page layouts, landing pages, and splash pages
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Page layouts, landing pages, and splash pages
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/styling/layouts.md)
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
+
+| Layout    | Sidebar | On this page | Use it for                                                                                                               |
+| --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `docs`    | Yes     | Yes          | Guides and reference pages. This is the default.                                                                         |
+| `wide`    | Yes     | No           | Wide tables, diagrams, and API overviews that need the full content width.                                               |
+| `landing` | No      | No           | Home pages and product entry points. A `Hero` replaces the page header.                                                  |
+| `splash`  | No      | No           | Marketing pages built from full-width bands. A `Hero` replaces the page header, and `Section` blocks stack edge to edge. |
+
+```yaml title="Frontmatter"
+layout: wide
+```
+
+An unknown value fails the build. Each preset styles all four layouts, and project CSS can target one through `html[data-layout="wide"]`, `html[data-layout="landing"]`, or `html[data-layout="splash"]`.
+
+## Control navigation tabs
+
+The built-in layouts are `docs`, `wide`, `landing`, and `splash`. There is no `custom` layout value; use landing or splash for a custom entry page and style it with project CSS.
+
+When the site config defines navigation tabs, docs and wide pages show the section bar by default. Landing and splash pages hide it by default. Override that choice on any page:
+
+```yaml title="Frontmatter"
+layout: splash
+showNavigationTabs: false
+```
+
+Set `showNavigationTabs: true` to include the tab bar on a landing or splash page. Set it to `false` to suppress it on a docs or wide page. The value must be a boolean and can also come from frontmatter defaults or enforced values. With no configured tabs, neither value creates a bar.
+
+This setting affects the HTML section bar only. It does not change the page's sidebar, tab membership, breadcrumbs, Markdown, search records, or agent indexes. An agent can still discover and read every published section without visiting the homepage.

package/agent-docs/styling/layouts.sections/customize-the-hero.md

@@ -0,0 +1,50 @@
+---
+id: guide.layouts
+title: Page layouts, landing pages, and splash pages
+summary: Configure wide, landing, and splash pages with Hero and Sections.
+type: reference
+area: appearance
+subarea: appearance-layouts
+canonical: /styling/layouts
+---
+
+# Page layouts, landing pages, and splash pages
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Page layouts, landing pages, and splash pages
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/styling/layouts.md)
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
+
+| Layout    | Sidebar | On this page | Use it for                                                                                                               |
+| --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `docs`    | Yes     | Yes          | Guides and reference pages. This is the default.                                                                         |
+| `wide`    | Yes     | No           | Wide tables, diagrams, and API overviews that need the full content width.                                               |
+| `landing` | No      | No           | Home pages and product entry points. A `Hero` replaces the page header.                                                  |
+| `splash`  | No      | No           | Marketing pages built from full-width bands. A `Hero` replaces the page header, and `Section` blocks stack edge to edge. |
+
+```yaml title="Frontmatter"
+layout: wide
+```
+
+An unknown value fails the build. Each preset styles all four layouts, and project CSS can target one through `html[data-layout="wide"]`, `html[data-layout="landing"]`, or `html[data-layout="splash"]`.
+
+## Customize the hero
+
+Each preset styles the hero its own way. `shoal` adds a soft accent glow, and `reef` uses a tinted panel with pill buttons. `ledger` sets it in an inked band, and `vice` in a night sky with a sunset stripe.
+
+To change it for your site, use [project CSS](https://www.shoalrun.com/author/css.md). The hero is a `section.hero` containing `.hero-title`, `.hero-tagline`, and `.hero-actions`. Its buttons are `.hero-primary` and `.hero-secondary`. Set `--landing-width` to change the landing page width:
+
+```css title="styles/project.css"
+:root { --landing-width: 64rem; }
+.content .hero { background: linear-gradient(135deg, #0b3d2e, #14532d); }
+.content .hero-title, .content .hero-tagline { color: #fff; }
+```
+
+Keep text readable against any background you choose. The build checks palette colors for contrast, but not project CSS.

package/agent-docs/styling/layouts.sections/hero.md

@@ -0,0 +1,83 @@
+---
+id: guide.layouts
+title: Page layouts, landing pages, and splash pages
+summary: Configure wide, landing, and splash pages with Hero and Sections.
+type: reference
+area: appearance
+subarea: appearance-layouts
+canonical: /styling/layouts
+---
+
+# Page layouts, landing pages, and splash pages
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Page layouts, landing pages, and splash pages
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/styling/layouts.md)
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
+
+| Layout    | Sidebar | On this page | Use it for                                                                                                               |
+| --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `docs`    | Yes     | Yes          | Guides and reference pages. This is the default.                                                                         |
+| `wide`    | Yes     | No           | Wide tables, diagrams, and API overviews that need the full content width.                                               |
+| `landing` | No      | No           | Home pages and product entry points. A `Hero` replaces the page header.                                                  |
+| `splash`  | No      | No           | Marketing pages built from full-width bands. A `Hero` replaces the page header, and `Section` blocks stack edge to edge. |
+
+```yaml title="Frontmatter"
+layout: wide
+```
+
+An unknown value fails the build. Each preset styles all four layouts, and project CSS can target one through `html[data-layout="wide"]`, `html[data-layout="landing"]`, or `html[data-layout="splash"]`.
+
+## Hero
+
+`Hero` opens a landing page with a large title, a tagline, and up to three action buttons. It can also show an image or a code block beside the text.
+
+| Attribute  | Required     | Meaning                                                                                     |
+| ---------- | ------------ | ------------------------------------------------------------------------------------------- |
+| `tagline`  | Yes          | One or two sentences under the title.                                                       |
+| `title`    | No           | The large title. Defaults to the page `title`.                                              |
+| `align`    | No           | `center` (default) or `start`, which aligns the title, tagline, and buttons to the left.    |
+| `image`    | No           | An https URL, or a local `.png`, `.jpg`, `.webp`, or `.svg` file relative to the page file. |
+| `imageAlt` | With `image` | What the image shows. Use `imageAlt=""` when the image is decorative.                       |
+
+Put the actions in the body as ordinary Markdown links, one per line or as a list. The first link is the primary button. `doc:` links resolve by page ID, like everywhere else.
+
+### Show an image or code
+
+Add `image` and `imageAlt` to show a picture beside the text. The build copies a local image to `/assets/pages/<page path>/`.
+
+```mdx
+<Hero tagline="Payments in five lines of code." image="./images/dashboard.png" imageAlt="The payments dashboard showing today's volume">
+  [Get started](doc:guide.start)
+</Hero>
+```
+
+Or put one fenced code block in the body. It appears in an editor-style window with its title and a Copy button, and keeps the site's code colors. The home page of this site uses one.
+
+````mdx
+<Hero tagline="Build API documentation from Markdown, MDX, and OpenAPI.">
+  [Start building](doc:guide.overview)
+
+  ```sh title="Build and preview this site"
+  npm ci --prefix framework
+  npm run docs:dev
+  ```
+</Hero>
+````
+
+With an image or code block, the hero splits into two columns, text first, and aligns to the left. Below `60rem` wide, the visual moves under the text. A hero can show an image or a code block, not both.
+
+### Rules
+
+- `Hero` needs `layout: landing` or `layout: splash`, and it replaces the page header, including the **Read as Markdown** link. Put it first on the page.
+- Attributes are literal text. The body can contain only action links and one code block; other content fails the build.
+- In the Markdown twin, `Hero` becomes the tagline, a list of its links, then its image (when `imageAlt` isn't empty) or its code block. A custom `title` that differs from the page title appears in bold before the tagline.
+
+Landing pages are centered and at most `76rem` wide, and the masthead lines up with them. On a phone, the hero stacks its buttons.

package/agent-docs/styling/layouts.sections/related-reading.md

@@ -0,0 +1,42 @@
+---
+id: guide.layouts
+title: Page layouts, landing pages, and splash pages
+summary: Configure wide, landing, and splash pages with Hero and Sections.
+type: reference
+area: appearance
+subarea: appearance-layouts
+canonical: /styling/layouts
+---
+
+# Page layouts, landing pages, and splash pages
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Page layouts, landing pages, and splash pages
+
+**Updated: 2026-10-26.**
+
+Parent page: [Full Markdown page](/styling/layouts.md)
+
+Every page uses the `docs` layout unless its frontmatter sets `layout`. Layouts change the HTML page only. The Markdown twin, search, and `llms.txt` stay the same.
+
+| Layout    | Sidebar | On this page | Use it for                                                                                                               |
+| --------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `docs`    | Yes     | Yes          | Guides and reference pages. This is the default.                                                                         |
+| `wide`    | Yes     | No           | Wide tables, diagrams, and API overviews that need the full content width.                                               |
+| `landing` | No      | No           | Home pages and product entry points. A `Hero` replaces the page header.                                                  |
+| `splash`  | No      | No           | Marketing pages built from full-width bands. A `Hero` replaces the page header, and `Section` blocks stack edge to edge. |
+
+```yaml title="Frontmatter"
+layout: wide
+```
+
+An unknown value fails the build. Each preset styles all four layouts, and project CSS can target one through `html[data-layout="wide"]`, `html[data-layout="landing"]`, or `html[data-layout="splash"]`.
+
+## Related reading
+
+### Reference while working
+
+- [CSS and theme reference](https://www.shoalrun.com/author/css.md) — Look up the width tokens and layout selectors.

package/agent-docs/styling/palettes.md

@@ -0,0 +1,140 @@
+---
+id: guide.palettes
+title: Color palettes
+summary: Use a built-in palette or extend one with your brand colors. The build
+  checks every palette against WCAG contrast.
+type: reference
+area: appearance
+subarea: appearance-themes
+canonical: /styling/palettes
+---
+
+# Color palettes
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Color palettes
+
+**Updated: 2026-10-26.**
+
+A palette sets every color token on the site, with one set for light mode and one for dark mode. Choose a built-in palette by name, or extend one with your own colors.
+
+## Built-in palettes
+
+Choose a built-in palette as the starting point for your site colors.
+
+| Palette    | Colors                                                                     |
+| ---------- | -------------------------------------------------------------------------- |
+| `kelp`     | Sea green on white. The light set matches the base tokens in `tokens.css`. |
+| `coral`    | Coral accent over cool blue-gray neutrals.                                 |
+| `ink`      | Black ink on warm paper with a vermilion accent.                           |
+| `harbor`   | Navy ink, blue links, and a yellow callout rule.                           |
+| `amethyst` | Violet accents over lavender neutrals.                                     |
+| `vice`     | Flamingo pink and aqua by day, and neon on a night-purple sky after dark.  |
+
+```yaml title="docs.config.yaml"
+theme:
+  palette: amethyst
+```
+
+Each [preset](https://www.shoalrun.com/styling/themes.md) has a default palette, so you only need `palette` to change it.
+
+## Add brand colors
+
+Extend a built-in palette and override only the tokens you need. Write token names without the `--color-` prefix:
+
+```yaml title="docs.config.yaml"
+theme:
+  palette:
+    extends: harbor
+    light:
+      accent: "#0a6a48"
+      link: "#0a6a48"
+      emphasis: "#0a6a48"
+    dark:
+      accent: "#4fd6a4"
+      accent-contrast: "#06231a"
+      link: "#7fe0bd"
+```
+
+`extends` defaults to the preset's palette. `light` and `dark` are both optional. Values must be three- or six-digit hex colors such as `"#0a6a48"`. Quote them, because YAML treats `#` as the start of a comment.
+
+To keep the colors in their own files, include each mode's token map and keep `extends` in the main config:
+
+```yaml title="docs.config.yaml"
+theme:
+  palette:
+    extends: harbor
+    light: { $include: ./styles/brand-light.yaml }
+    dark: { $include: ./styles/brand-dark.yaml }
+```
+
+```yaml title="styles/brand-light.yaml"
+accent: "#0a6a48"
+link: "#0a6a48"
+```
+
+Don't include a file that sets `extends` at its top level. The config loader reads a top-level `extends` in any config file as a list of [config presets](https://www.shoalrun.com/config.md), so `extends: harbor` there fails the build.
+
+Most brands need four tokens or fewer:
+
+| Token                   | Controls                                                         |
+| ----------------------- | ---------------------------------------------------------------- |
+| `accent`                | Brand mark, primary header button, and active navigation marker. |
+| `accent-contrast`       | Text on `accent`, such as the primary button label.              |
+| `link` and `link-hover` | Links at rest and on hover.                                      |
+| `emphasis`              | Eyebrows, card icons, and search highlights.                     |
+
+The [CSS and theme reference](https://www.shoalrun.com/author/css.md) lists every token.
+
+## Contrast checks
+
+The build checks each palette against WCAG 2.2 before it writes any files. It checks the light set, the dark set, or both, depending on the [mode](https://www.shoalrun.com/styling/color-modes.md). If a pair fails, the build stops and names it:
+
+```text
+Theme colors fail WCAG 2.2 contrast:
+  - light: link #9fe6cc on page #ffffff is 1.40:1; needs 4.5:1
+```
+
+Success criterion 1.4.3 requires 4.5:1 for text against its background.
+
+Success criterion 1.4.11 requires 3:1 for focus rings, form field borders, and the accent fill against the page.
+
+The build checks these pairs:
+
+- Body text, muted text, links, headings, navigation text, and summaries on the page, surface, and field backgrounds.
+- Hovered links, callout text, and inline code on their backgrounds.
+- Body text, links, and labels in each callout type: note, tip, important, warning, and caution.
+- Body text, links, and labels on each custom callout tone from `callouts.tones`.
+- Active navigation, subject lifecycle badges, and required and optional field badges.
+- Code text and code labels on code blocks.
+- `accent-contrast` on `accent`, and `strong-text` on `strong-surface`.
+- `focus`, `field-border`, and `accent` against the page and surface.
+
+Every built-in palette passes in both modes. The framework tests check them on every change.
+
+### Check colors in CI
+
+`shoalrun config validate` runs the same check without building the site. It prints the same messages and exits with status 1 when a pair fails, so a CI step can stop a change before it merges:
+
+```bash
+shoalrun config validate docs.config.yaml
+```
+
+On success, its JSON output includes `"contrast": { "status": "ok", "palette": "kelp", "modes": ["light"] }`.
+
+[`shoalrun audit`](https://www.shoalrun.com/publish/audit.md) also fails on a contrast problem, because it builds the site.
+
+The check covers palette colors only. Colors you set in [project CSS](https://www.shoalrun.com/author/css.md), and syntax colors from a named Shiki theme, are not checked. Test those yourself. The default `site` code theme derives its syntax colors from the palette and replaces any that fall below 4.5:1 with plain code text.
+
+## Related reading
+
+### Read first
+
+- [Themes](https://www.shoalrun.com/styling/themes.md) — Pick the preset that the palette colors.
+
+### Related topics
+
+- [Light and dark mode](https://www.shoalrun.com/styling/color-modes.md) — A palette has one color set for light mode and one for dark mode.

package/agent-docs/styling/share-images.md

@@ -0,0 +1,105 @@
+---
+id: guide.share-images
+title: Share images and favicon
+summary: Generated social images, metadata precedence, SVG placeholders, fonts,
+  and favicon settings.
+type: reference
+area: appearance
+subarea: appearance-branding
+canonical: /styling/share-images
+---
+
+# Share images and favicon
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Share images and favicon
+
+**Updated: 2026-10-26.**
+
+When someone pastes a page link into Slack, LinkedIn, or X, the preview shows an image. Shoalrun draws one for every page at build time and adds the tags those apps read. It also generates a favicon. Both follow the site's preset and palette, so they need no setup.
+
+For the author workflow around page titles, summaries, public URLs, and social metadata, start with [SEO and social previews](https://www.shoalrun.com/publish/seo.md).
+
+## What the build writes
+
+- A 1200×630 PNG per page at `/assets/share/<page path>.png`, such as `/assets/share/styling/themes.png`. It shows the page type, title, and summary, the site title, and the page URL.
+- `og:title`, `og:description`, and `og:image` tags, plus explicit `twitter:title`, `twitter:description`, `twitter:image`, and `twitter:card` tags. The description uses the same page text as the image.
+- `/favicon.svg`, drawn from the preset's brand mark in the accent color, and a 180×180 `/apple-touch-icon.png`.
+
+Set `site.origin` to the public site address so image and page URLs in the tags are absolute and publicly reachable. A browser can load a page even when a link-preview crawler cannot fetch an image hosted at a different or private address. Run the [deployment checker](https://www.shoalrun.com/publish/deployment-check.md) against the public origin to catch a mismatched `og:image` or a missing image.
+
+```yaml title="docs.config.yaml"
+site:
+  title: Acme API docs
+  origin: https://docs.acme.com
+```
+
+The preview description comes from the page's `displayText.socialCard`, `seo.description`, configured HTML description, or `summary`, in that order. The same text appears in `og:description` and on the generated image. Long titles wrap to three lines and long summaries to two, ending in an ellipsis.
+
+For a short page title such as **Getting started**, the social title adds the site name when the result fits within 70 characters. The page heading and browser title stay as authored. Set `seo.title` on a page when you want to choose its exact social title instead.
+
+The build caches rendered images in `.shoalrun/cache/share-images/` beside the config file and redraws only pages whose card changed. Add `.shoalrun/` to `.gitignore`.
+
+## Use your own image for a page
+
+Set `image` in frontmatter to a local `.png` or `.jpg`, relative to the page file. It replaces the generated card for that page. 1200×630 works best.
+
+```yaml title="Frontmatter"
+image: ./images/launch.png
+```
+
+## Replace the design
+
+Point `outputs.html.shareImages.template` at a 1200×630 SVG file. The build fills these placeholders on each page:
+
+| Placeholder                                 | Value                                                       |
+| ------------------------------------------- | ----------------------------------------------------------- |
+| `{{title}}`, `{{summary}}`                  | The full title and summary.                                 |
+| `{{title.1}}`, `{{title.2}}`, `{{title.3}}` | The title split into lines of about 30 characters.          |
+| `{{summary.1}}`, `{{summary.2}}`            | The summary split into lines of about 60 characters.        |
+| `{{site}}`                                  | `site.title`.                                               |
+| `{{type}}`                                  | The page type as words, such as `API reference`.            |
+| `{{url}}`                                   | The page URL without `https://`, when `site.origin` is set. |
+
+```yaml title="docs.config.yaml"
+outputs:
+  html:
+    shareImages:
+      template: ./share/card.svg
+      fonts: [./share/AcmeSans-Bold.ttf]
+```
+
+```xml title="share/card.svg"
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630">
+  <rect width="1200" height="630" fill="#0b3d2e"/>
+  <text x="80" y="220" font-family="Acme Sans" font-weight="700" font-size="64" fill="#ffffff">{{title.1}}</text>
+  <text x="80" y="296" font-family="Acme Sans" font-weight="700" font-size="64" fill="#ffffff">{{title.2}}</text>
+  <text x="80" y="560" font-family="Inter" font-size="26" fill="#cfe8dd">{{site}}</text>
+</svg>
+```
+
+- An unknown placeholder fails the build, so a typo can't publish raw braces.
+- The renderer doesn't load system fonts. It can use Inter, Figtree, Source Serif 4, JetBrains Mono, and Jost, plus any `.ttf` or `.otf` files listed in `fonts` or in [`theme.fonts`](https://www.shoalrun.com/styling/themes.md).
+- The renderer reads TrueType and OpenType files only. WOFF2 files from `theme.fonts` still work on the site, but not in share images.
+
+To turn generated images off, set `shareImages: false`. Pages with their own `image` keep it.
+
+## Replace the favicon
+
+Set `site.favicon` to a local `.svg` or `.png`. An SVG favicon also becomes the touch icon, placed on the palette's inked surface. A PNG favicon is used as is, with no separate touch icon.
+
+```yaml title="docs.config.yaml"
+site:
+  favicon: ./brand/mark.svg
+```
+
+A missing file or another format fails the build.
+
+## Related reading
+
+### Read first
+
+- [Themes](https://www.shoalrun.com/styling/themes.md) — Set the theme that generated share images and the favicon take their look from.

package/agent-docs/styling/themes.md

@@ -0,0 +1,125 @@
+---
+id: guide.themes
+title: Themes
+summary: Pick a site shape, pair it with a color palette, and choose how light
+  and dark mode behave.
+type: reference
+area: appearance
+subarea: appearance-themes
+canonical: /styling/themes
+---
+
+# Themes
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Customize > Themes
+
+**Updated: 2026-10-26.**
+
+The `theme` setting controls how the HTML site looks. It has five keys, and each has a default:
+
+```yaml title="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](https://www.shoalrun.com/styling/try.md).
+
+Start with a preset. Change the [palette](https://www.shoalrun.com/styling/palettes.md) if its colors don't fit your brand. Set the [mode](https://www.shoalrun.com/styling/color-modes.md) if readers need dark mode. Use [project CSS](https://www.shoalrun.com/author/css.md) 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.
+
+```yaml title="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](https://www.shoalrun.com/author/css.md) 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](https://www.shoalrun.com/author/css.md), 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](https://www.shoalrun.com/styling/try.md).
+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:
+
+```css title="styles/project.css"
+[data-theme="ledger"] .page-head h1 { letter-spacing: 0; }
+```
+
+## Related reading
+
+### Next steps
+
+- [Color palettes](https://www.shoalrun.com/styling/palettes.md) — Choose the colors the preset uses.
+
+- [Light and dark mode](https://www.shoalrun.com/styling/color-modes.md) — Decide whether readers get light mode, dark mode, or a toggle.
+
+### Go deeper
+
+- [CSS and theme reference](https://www.shoalrun.com/author/css.md) — Customize tokens and selectors beyond what presets and palettes offer.
+
+### Related topics
+
+- [Try a theme](https://www.shoalrun.com/styling/try.md) — Preview every preset, palette, and color mode on a live page.