From f836e320b3413e96328bc9f54595376c6849cc86 Mon Sep 17 00:00:00 2001 From: kbenestad Date: Mon, 18 May 2026 22:15:13 +0700 Subject: [PATCH] Update reference-theme.md with all new theme.yml keys (nav colours, semantic-dark, toggle icons) Adds documentation for: - nav-link, nav-link-active, nav-section-heading (per mode) - nav-sitename, nav-description, nav-toggle (per mode) - divider (per mode, auto-derived by default) - colours-semantic-dark (dark mode semantic colour overrides) - nav-section-expand-icon / nav-section-collapse-icon (top-level toggle icons) https://claude.ai/code/session_01NQKywehSj8Ku4yKhwB4VNB --- docs/reference-theme.md | 121 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 118 insertions(+), 3 deletions(-) diff --git a/docs/reference-theme.md b/docs/reference-theme.md index 282812f..f47220c 100644 --- a/docs/reference-theme.md +++ b/docs/reference-theme.md @@ -14,6 +14,8 @@ theme: theme.yml `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 + ```yaml light: accent: "#2563EB" # Primary accent — links, active nav item, focus rings. @@ -21,6 +23,8 @@ light: 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" @@ -28,15 +32,37 @@ dark: 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). +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. + +```yaml +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`). These are mode-independent — choose values that look acceptable on both light and dark backgrounds, or accept that they are a compromise. +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. ```yaml colours-semantic: @@ -44,13 +70,21 @@ colours-semantic: 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 low opacity by the renderer). +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). ```yaml callouts: @@ -79,6 +113,29 @@ Individual callout blocks in markdown can override the icon with `icon: `. --- +## 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. + +```yaml +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"` @@ -135,6 +192,9 @@ light: 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" @@ -149,6 +209,12 @@ colours-semantic: success: "#16A34A" error: "#DC2626" +colours-semantic-dark: + info: "#60A5FA" + warning: "#F59E0B" + success: "#34D399" + error: "#F87171" + callouts: info: icon: info @@ -167,6 +233,9 @@ callouts: 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" @@ -176,3 +245,49 @@ 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: + +```yaml +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" +```