Add theme customization support via docs.yaml

gbasran · gbasran · commit 52c4200e25bc · 2026-02-17T01:24:47.000-07:00
diff --git a/phosphor/config.py b/phosphor/config.py
@@ -12,6 +12,7 @@
         "github": "",
         "favicon": "",
     },
+    "theme": {},
     "nav": [],
     "pages": [],
 }
@@ -32,6 +33,7 @@ def load_config(config_path):
     site.update(raw.get("site", {}))
     cfg["site"] = site
 
+    cfg["theme"] = raw.get("theme", DEFAULTS["theme"])
     cfg["nav"] = raw.get("nav", DEFAULTS["nav"])
     cfg["pages"] = raw.get("pages", DEFAULTS["pages"])
 
diff --git a/phosphor/renderer.py b/phosphor/renderer.py
@@ -56,6 +56,46 @@ def build_toc_html(headings):
     return html
 
 
+def build_theme_css(theme_config):
+    """Build CSS variable overrides from theme config."""
+    if not theme_config:
+        return ""
+
+    # Map docs.yaml theme keys to CSS custom properties
+    key_map = {
+        "accent": "--accent",
+        "accent_dim": "--accent-dim",
+        "accent_glow": "--accent-glow",
+        "accent_glow_strong": "--accent-glow-strong",
+        "accent_warm": "--accent-warm",
+        "accent_warm_dim": "--accent-warm-dim",
+        "accent_red": "--accent-red",
+        "accent_blue": "--accent-blue",
+        "accent_purple": "--accent-purple",
+        "bg_deep": "--bg-deep",
+        "bg_surface": "--bg-surface",
+        "bg_raised": "--bg-raised",
+        "bg_hover": "--bg-hover",
+        "code_bg": "--code-bg",
+        "text": "--text",
+        "text_bright": "--text-bright",
+        "text_dim": "--text-dim",
+        "border": "--border",
+        "border_bright": "--border-bright",
+    }
+
+    overrides = []
+    for yaml_key, css_var in key_map.items():
+        if yaml_key in theme_config:
+            overrides.append(f"    {css_var}: {theme_config[yaml_key]};")
+
+    if not overrides:
+        return ""
+
+    lines = "\n".join(overrides)
+    return f"<style>\n  :root {{\n{lines}\n  }}\n</style>"
+
+
 def render_page(template, config, page_content, nav_html, page_filename):
     """Render a page by substituting variables into the template."""
     site = config["site"]
@@ -84,8 +124,12 @@ def render_page(template, config, page_content, nav_html, page_filename):
             f'</a>'
         )
 
+    # Theme overrides
+    theme_css = build_theme_css(config.get("theme", {}))
+
     # Substitutions
     output = template
+    output = output.replace("{{THEME_CSS}}", theme_css)
     output = output.replace("{{TITLE}}", _escape(page_title))
     output = output.replace("{{SITE_TITLE}}", _escape(site["title"]))
     output = output.replace("{{TAGLINE}}", _escape(site.get("tagline", "")))
diff --git a/templates/base.html b/templates/base.html
@@ -9,6 +9,7 @@
   <link href="https://fonts.googleapis.com/css2?family=Chakra+Petch:ital,wght@0,400;0,500;0,600;0,700;1,400&family=Nunito+Sans:opsz,wght@6..12,400;6..12,500;6..12,600;6..12,700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
   <link rel="icon" type="image/svg+xml" href="{{FAVICON}}">
   <link rel="stylesheet" href="assets/style.css">
+  {{THEME_CSS}}
 </head>
 <body>
   <button class="mobile-toggle" onclick="document.querySelector('.sidebar').classList.toggle('open')" aria-label="Toggle menu"><i data-lucide="menu"></i></button>
