mirror of
https://github.com/kbenestad/mdcms.git
synced 2026-06-18 07:24:31 +00:00
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
This commit is contained in:
parent
f9f3b9b81b
commit
f836e320b3
1 changed files with 118 additions and 3 deletions
|
|
@ -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: <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.
|
||||
|
||||
```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"
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in a new issue