# theme.yml reference

`theme.yml` controls the visual presentation of your site. It is separate from `config.yml` so you can update colours and fonts without touching site settings, and vice versa. `index.html` loads it at runtime — no build step required.

Point `config.yml` at it with:

```yaml
theme: theme.yml
```

---

## Colours — light and dark mode

`light` and `dark` are the two mode blocks. Both accept the same keys. mdcms switches between them based on the user's system preference or the theme toggle.

```yaml
light:
  accent: "#2563EB"            # Primary accent — links, active nav item, focus rings.
  background: "#FFFFFF"        # Main content area background.
  nav-background: "#F8FAFC"    # Sidebar / topbar background.
  text: "#1E293B"              # Body text colour.
  text-muted: "#64748B"        # Secondary text — descriptions, timestamps, captions.

dark:
  accent: "#60A5FA"
  background: "#0F172A"
  nav-background: "#1E293B"
  text: "#F1F5F9"
  text-muted: "#94A3B8"
```

All values are CSS colour strings (hex, `rgb()`, `hsl()`, named colours).

---

## Semantic colours

Used by callout tags (`callout-info`, `callout-warning`, `callout-success`, `callout-error`). These are mode-independent — choose values that look acceptable on both light and dark backgrounds, or accept that they are a compromise.

```yaml
colours-semantic:
  info: "#2563EB"
  warning: "#D97706"
  success: "#16A34A"
  error: "#DC2626"
```

---

## Callout defaults

Overrides the icon and colour used for each callout type. `primary-colour` sets the left border; `background-colour` sets the tinted background fill (applied at low opacity by the renderer).

```yaml
callouts:
  info:
    icon: info                    # SVG icon name from assets/icons/ (without .svg)
    primary-colour: "#2563EB"     # Left border colour
    background-colour: "#2563EB"  # Background tint colour

  warning:
    icon: warning
    primary-colour: "#D97706"
    background-colour: "#D97706"

  success:
    icon: success
    primary-colour: "#16A34A"
    background-colour: "#16A34A"

  error:
    icon: error
    primary-colour: "#DC2626"
    background-colour: "#DC2626"
```

Individual callout blocks in markdown can override the icon with `icon: <name>`.

---

## Typography

Font format: `"provider:Font Name:weight"`

- `provider`: `bunny` (privacy-friendly, GDPR-safe) or `google`
- `Font Name`: exact font family name as listed on the font provider
- `weight`: numeric CSS weight (`400`, `700`, etc.)

```yaml
font-body: "bunny:Noto Sans:400"      # Body text font
font-heading: "bunny:Noto Sans:700"   # Headings (h1–h6) font
font-code: "bunny:Fira Code:400"      # Code blocks and inline code
```

System fonts (no external request):

```yaml
font-body: "system-ui:400"
```

Shorthand without provider defaults to Google Fonts:

```yaml
font-body: "Noto Sans:400"    # equivalent to google:Noto Sans:400
```

Size and spacing:

```yaml
font-size: 1.0      # Unitless multiplier. 1.0 = 16px base. 1.125 = 18px.
line-height: 1.7    # Unitless multiplier for body text line spacing.
```

---

## Layout

```yaml
main-width: 80em    # Maximum width of the content column. Any CSS length unit.
nav-width: 20em     # Width of the sidebar. Any CSS length unit.
```

---

## Full example

```yaml
# mdcms v0.4 | DO NOT REMOVE THIS COMMENT
# MD-CMS v0.4 — Theme configuration

light:
  accent: "#2563EB"
  background: "#FFFFFF"
  nav-background: "#F8FAFC"
  text: "#1E293B"
  text-muted: "#64748B"

dark:
  accent: "#60A5FA"
  background: "#0F172A"
  nav-background: "#1E293B"
  text: "#F1F5F9"
  text-muted: "#94A3B8"

colours-semantic:
  info: "#2563EB"
  warning: "#D97706"
  success: "#16A34A"
  error: "#DC2626"

callouts:
  info:
    icon: info
    primary-colour: "#2563EB"
    background-colour: "#2563EB"
  warning:
    icon: warning
    primary-colour: "#D97706"
    background-colour: "#D97706"
  success:
    icon: success
    primary-colour: "#16A34A"
    background-colour: "#16A34A"
  error:
    icon: error
    primary-colour: "#DC2626"
    background-colour: "#DC2626"

font-body: "bunny:Noto Sans:400"
font-heading: "bunny:Noto Sans:700"
font-code: "bunny:Fira Code:400"
font-size: 1.0
line-height: 1.7

main-width: 80em
nav-width: 20em
```