Theming & Custom Styling

Customize colors, typography, CSS design tokens, and layout aesthetics across your Metupy documentation site.

1. Core CSS Variables

Metupy uses native CSS custom properties for effortless theming and dark mode transitions:

CSS Variable	Light Mode Default	Dark Mode Default	Usage Description
`--bg-base`	`#ffffff`	`#09090b`	Main viewport and page background
`--bg-surface`	`#f4f4f5`	`#18181b`	Card, table header, and component surface color
`--text-main`	`#09090b`	`#f4f4f5`	Primary heading and body text color
`--text-muted`	`#71717a`	`#a1a1aa`	Subtitles, active borders, and secondary text
`--accent`	`#2563eb`	`#3b82f6`	Primary brand color for links, buttons, and highlights
`--border-color`	`#e4e4e7`	`#27272a`	Global divider and component border color
`--font-sans`	`'Inter', system-ui, sans-serif`	Same	Primary font stack used across the entire document

2. Theme Configuration

Set your active theme and configuration options inside pyproject.toml:

pyproject.toml

[project]
name = "My Documentation Site"

[tool.metupy]
theme = "default"
use_darkmode = true

3. Dark Mode Integration

Automatic Persistence

When use_darkmode = true is enabled in pyproject.toml, Metupy dynamically toggles the [data-theme='dark'] attribute on the HTML element and remembers user preferences.

Custom Fonts & Head Injection

To introduce external fonts (like Google Fonts) or custom CSS files, place your custom layout.html inside templates/{theme_name}/layout.html and inject font links directly into the <head> tag.