mirror of
https://github.com/kbenestad/mdcms.git
synced 2026-06-18 15:24:32 +00:00
kbenestad
f836e320b3
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
293 lines
8.5 KiB
Markdown
293 lines
8.5 KiB
Markdown
# 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.
|
||
|
||
### Base colours
|
||
|
||
```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.
|
||
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.
|
||
|
||
```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`). `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:
|
||
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).
|
||
|
||
```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>`.
|
||
|
||
---
|
||
|
||
## 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"`
|
||
|
||
- `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"
|
||
# 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:
|
||
|
||
```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"
|
||
```
|