mdcms/docs/reference-theme.md

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:

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.

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.

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).

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.)

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):

font-body: "system-ui:400"

Shorthand without provider defaults to Google Fonts:

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

Size and spacing:

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

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

# 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