Theme

A theme bundles layout decisions (header rows, tab position, sidebar style, breadcrumb style) with CSS tokens (colors, typography, spacing, radius). You pick a theme by slug in nookdocs.config.json#theme, then override any piece with colors, background, typography, and appearance. Dark mode is automatic — every token has a light + dark value.

{
  "$schema": "https://nookdocs.com/schema.json",
  "name": "Acme Docs",
  "theme": "cedar",
  "colors": {
    "primary": "#0ea5e9",
    "logo": { "light": "/logo/light.svg", "dark": "/logo/dark.svg" }
  },
  "appearance": { "default": "system" }
}

Theme catalog

Ten presets ship out of the box. Each is a ThemeDefinition at src/lib/theme/themes/<slug>.ts that wires layout knobs to the shared token base.

Backward-compatible aliases also resolve: maple → larch (renamed 2026-05-05), classic → cedar, modern → ember, minimal → sage.

Where your navigation lands

The theme decides where each piece of chrome sits. Same navigation array, same navbar config — different placement:

Nothing here is fixed. navbar.controls moves any control to "header" or "sidebar" regardless of the theme — in the dashboard under Configurations → Site → Navbar, where each control has a Theme default option that writes nothing to your config. See Site settings.

On narrow screens and phones every theme behaves the same way: the rail and the tab strip step aside, and search, the assistant and a breadcrumb appear in a row beside the menu button.

Appearance (light / dark)

Controls the default color-scheme and whether visitors can toggle it.

Brand colors

Four overrides layer on top of the active theme's token palette. Leave any of them unset to inherit from the theme.

Background

Each theme ships its own background. Cedar paints a spotlight gradient, Obsidian a near-black #09090b, Terminal a warm cream — you get the theme's own tone automatically. background is an optional override: set it only when you want something other than the theme default.

• Omit background → the active theme's background is used.

• Set background.light and/or background.dark → that mode is overridden; the other mode still inherits the theme. Partial overrides (dark-only, light-only) are fully supported.

Solid colors or CSS gradients both work — anything the browser accepts for background, including linear-gradient(...), radial-gradient(...), and CSS custom properties.

Typography

Emitted as CSS custom properties (--docs-font-sans, --docs-font-heading, --docs-font-body) and read by every theme. Load the font files yourself (Google Fonts <link>, @font-face in custom-scripts, or a system-font stack).

{
  "typography": {
    "headingFont": "'Geist', system-ui, sans-serif",
    "bodyFont": "'Inter', system-ui, sans-serif"
  }
}

Complete example

Paste-ready block combining every appearance-related key. Drop into your nookdocs.config.json, tweak slugs/colors/paths, deploy.

{
  "$schema": "https://nookdocs.com/schema.json",
  "name": "Acme Docs",
  "theme": "larch",
  "appearance": {
    "default": "system",
    "strict": false
  },
  "colors": {
    "primary": "#0ea5e9",
    "light": "#0284c7",
    "dark": "#38bdf8",
    "logo": {
      "light": "/logo/acme-light.svg",
      "dark": "/logo/acme-dark.svg",
      "href": "https://acme.com"
    }
  },
  "background": {
    "light": "#ffffff",
    "dark": "radial-gradient(at top, #0f172a 0%, #020617 100%)"
  },
  "typography": {
    "headingFont": "'Geist', system-ui, sans-serif",
    "bodyFont": "'Inter', system-ui, sans-serif"
  }
}

Precedence rules

When multiple values could apply, NookDocs resolves in this order (last wins):

1. Theme default — themes/<slug>.ts ships tokensLight + tokensDark (including the background)

2. colors.primary — used for both modes when no per-mode override

3. colors.light / colors.dark — overrides per-mode

4. background.* / typography.* — optional overrides, emitted as CSS custom properties at #docs-root scope. A given mode is only overridden when its background key is present; otherwise the theme background stands.

5. Preview header — ?preview_theme=<slug> (editor only) swaps the active theme definition at render time

This means colors.dark always wins over colors.primary in dark mode, and any per-tenant override always wins over the theme defaults — but an absent background key means "use the theme," not "use white/black."

Editing from the dashboard

Configurations → Site surfaces every field above. When you pick a theme, the accent and background fields preview that theme's own colors; they're only written to nookdocs.config.json if you edit them, and each field has a Reset to theme action to drop the override and fall back to the theme default. A field showing Theme default is following the theme and will keep following it through future theme switches — so you can try several themes and see each one's real palette, then pin only the colors you actually want to differ. The dashboard writes back to nookdocs.config.json in your repo on save (git commit via the GitHub App), so dashboard edits and hand-edits stay in sync. Run npm run check:sync before committing schema additions — see schema reference for the validator rules.

Related

• Schema reference — auto-generated field-by-field reference for every nookdocs.config.json key

• Brand — favicon, OG image, manifest, PWA assets beyond logos

• Custom domain — DNS, SSL, and canonical URL setup

• Site settings — banner, SEO, redirects, footer, navbar