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.

Base colours

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.
  divider: "#CBD5E1"           # Border and hr colour.
                               # Omit to auto-derive: color-mix(background 85%, text).

dark:
  accent: "#60A5FA"
  background: "#0F172A"
  nav-background: "#1E293B"
  text: "#F1F5F9"
  text-muted: "#94A3B8"
  divider: "#334155"           # Omit to auto-derive.

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

Nav colours

These control every element inside the sidebar. When nav-background is a neutral near-white or near-black the defaults (which fall back to the base colours) work fine and can be omitted. Set them explicitly whenever nav-background is a saturated brand colour, a dark sidebar in an otherwise light design, or any noticeably tinted background.

light:
  # Nav links and section labels
  nav-link: "#1E293B"              # Inactive nav link text. Defaults to text.
  nav-link-active: "#2563EB"       # Active (current page) nav link. Defaults to accent.
  nav-section-heading: "#64748B"   # Section label text (uppercase, small). Defaults to text-muted.

  # Sidebar header elements
  nav-sitename: "#1E293B"          # Site name in the sidebar header. Defaults to nav-link.
  nav-description: "#64748B"       # Site description below the site name. Defaults to nav-section-heading.
  nav-toggle: "#64748B"            # Dark/light mode toggle button. Defaults to nav-section-heading.

The same keys apply in the dark: block.

When nav-background is a bold colour (e.g. brand red, navy, deep green), set all six nav keys explicitly so links, labels, the site name, description, and toggle are all legible against the nav background. A common pattern is white (#FFFFFF) for nav-link, nav-link-active, and nav-sitename, and a semi-transparent white (e.g. rgba(255,255,255,0.65)) for nav-section-heading, nav-description, and nav-toggle.

---

Semantic colours

Used by callout tags (callout-info, callout-warning, callout-success, callout-error). colours-semantic applies to both modes. colours-semantic-dark overrides for dark mode only — use lighter, more luminous variants so callout borders and tinted backgrounds remain legible on dark page backgrounds.

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

colours-semantic-dark:
  info: "#60A5FA"      # Lighter blue — visible on dark background
  warning: "#F59E0B"
  success: "#34D399"
  error: "#F87171"

If colours-semantic-dark is omitted, the colours-semantic values are used in both modes.

---

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 ~8% 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>.

---

Nav section toggle icons

Sections with pagesvisibility: hidden in nav.yml are collapsible. These two top-level keys (not inside light:/dark:) set the icons used for the toggle.

nav-section-expand-icon: arrow_right       # Shown when section is collapsed. Default: arrow_right.
nav-section-collapse-icon: arrow_drop_down # Shown when section is expanded. Default: arrow_drop_down.

Available icon names:

Expand	Collapse	Style
arrow_right	arrow_drop_down	Solid filled triangles (default)
keyboard_arrow_right	keyboard_arrow_down	Chevrons — lighter, more modern
keyboard_double_arrow_right	keyboard_double_arrow_down	Double chevrons — emphatic
expand_content	collapse_content	Corner arrows — editorial
add	minimize	Plus / minus — minimal

The two keys are independent — expand and collapse do not have to use icons from the same pair, though keeping a consistent visual weight reads better.

---

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"
  # nav-link, nav-link-active, nav-section-heading, nav-sitename,
  # nav-description, nav-toggle — omit when nav-background is neutral.
  # divider — omit to auto-derive from background + text.

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

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

colours-semantic-dark:
  info: "#60A5FA"
  warning: "#F59E0B"
  success: "#34D399"
  error: "#F87171"

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"

# nav-section-expand-icon: arrow_right
# nav-section-collapse-icon: arrow_drop_down

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

---

Bold nav background example

When nav-background matches or is close to accent, set all nav colour keys explicitly:

light:
  accent: "#D00C33"
  background: "#FFFFFF"
  nav-background: "#D00C33"
  text: "#1A1A1A"
  text-muted: "#5C5C5C"
  nav-link: "#FFFFFF"
  nav-link-active: "#FFFFFF"
  nav-section-heading: "rgba(255,255,255,0.65)"
  nav-sitename: "#FFFFFF"
  nav-description: "rgba(255,255,255,0.65)"
  nav-toggle: "rgba(255,255,255,0.65)"

dark:
  accent: "#D00C33"
  background: "#0A0A0A"
  nav-background: "#000000"
  text: "#FFFFFF"
  text-muted: "#A89090"
  nav-link: "#E2E2E2"
  nav-link-active: "#FFFFFF"
  nav-section-heading: "#888888"
  nav-sitename: "#FFFFFF"
  nav-description: "#888888"
  nav-toggle: "#888888"

colours-semantic:
  info: "#D00C33"
  warning: "#B26A1F"
  success: "#2F7A4A"
  error: "#D00C33"

colours-semantic-dark:
  info: "#FF6B6B"
  warning: "#F59E0B"
  success: "#34D399"
  error: "#FF6B6B"