fix(theme): respect system color-scheme preference on initial page load

micahkepe · micahkepe · commit 2c7c674ececd · 2026-03-27T09:17:51.000-07:00
Fix by reading the theme config from a data-theme attribute on &lt;html&gt;
(rendered by Zola), falling back to matchMedia for system preference,
forcing syntax highlighting stylesheets to match, and only persisting
to localStorage on explicit toggle clicks.
diff --git a/static/js/init-theme.js b/static/js/init-theme.js
@@ -7,16 +7,22 @@
 
 (function () {
   try {
-    const storedTheme = localStorage.getItem("theme-storage");
-    const defaultTheme = "{{ config.extra.theme | default(value='toggle') }}";
-    let theme;
+    var storedTheme = localStorage.getItem("theme-storage");
+    var defaultTheme = document.documentElement.dataset.theme || "toggle";
+    var theme;
 
-    if (["light", "dark", "auto"].includes(defaultTheme)) {
+    if (defaultTheme === "light" || defaultTheme === "dark") {
       theme = defaultTheme;
-    } else if (storedTheme) {
-      theme = storedTheme;
+    } else if (defaultTheme === "auto" || defaultTheme === "toggle") {
+      if (storedTheme === "light" || storedTheme === "dark") {
+        theme = storedTheme;
+      } else {
+        theme = window.matchMedia("(prefers-color-scheme: dark)").matches
+          ? "dark"
+          : "light";
+      }
     } else {
-      theme = "dark"; // fallback default
+      theme = "dark";
     }
 
     // Apply theme class directly
@@ -25,14 +31,21 @@
     if (document.body) {
       document.body.classList.add(theme);
     } else {
-      // Defer body class application
       window.addEventListener("DOMContentLoaded", function () {
         document.body.classList.add(theme);
       });
     }
+
+    // Force syntax highlighting stylesheets to match the resolved theme.
+    // Without this, the browser applies them based on OS prefers-color-scheme,
+    // which may not match the stored user preference.
+    var d = document.getElementById("giallo-dark");
+    var l = document.getElementById("giallo-light");
+    if (d && l) {
+      d.media = theme === "dark" ? "all" : "not all";
+      l.media = theme === "light" ? "all" : "not all";
+    }
   } catch (e) {
-    // In case localStorage access fails
     document.documentElement.classList.add("dark");
-    document.body.classList.add("dark");
   }
 })();
diff --git a/static/js/toggle-theme.js b/static/js/toggle-theme.js
@@ -10,23 +10,18 @@ document.addEventListener("DOMContentLoaded", function () {
   const defaultThemeOption = document.documentElement.dataset.theme || "toggle";
   let currentTheme = storedTheme || defaultThemeOption;
 
-  // Prioritize `config.extra.theme` over localStorage, if available
-  if (
-    defaultThemeOption === "dark" ||
-    defaultThemeOption === "light" ||
-    defaultThemeOption === "auto"
-  ) {
+  if (defaultThemeOption === "dark" || defaultThemeOption === "light") {
+    // Fixed theme set in config
     currentTheme = defaultThemeOption;
-  } else if (storedTheme) {
+  } else if (storedTheme === "light" || storedTheme === "dark") {
+    // User explicitly toggled before — respect their choice
     currentTheme = storedTheme;
   } else {
-    // Set to prefer user system preference, if available, else default to dark
+    // No explicit choice — follow system preference
     try {
-      const systemTheme = window.matchMedia("(prefers-color-scheme: dark)")
-        .matches
+      currentTheme = window.matchMedia("(prefers-color-scheme: dark)").matches
         ? "dark"
         : "light";
-      currentTheme = systemTheme;
     } catch (e) {
       currentTheme = "dark";
     }
@@ -53,11 +48,14 @@ document.addEventListener("DOMContentLoaded", function () {
 });
 
 /**
- * Updates the theme mode in local storage and applies it to the page.
+ * Updates the theme mode and applies it to the page.
  * @param {string} mode - The theme mode to set ("light" or "dark").
+ * @param {boolean} [persist=false] - Whether to save the choice to localStorage.
  */
-function setTheme(mode) {
-  localStorage.setItem("theme-storage", mode);
+function setTheme(mode, persist) {
+  if (persist) {
+    localStorage.setItem("theme-storage", mode);
+  }
   document.documentElement.classList.remove("light", "dark");
   document.body.classList.remove("light", "dark");
 
@@ -105,7 +103,7 @@ function toggleTheme() {
   const newTheme = document.documentElement.classList.contains("dark")
     ? "light"
     : "dark";
-  setTheme(newTheme);
+  setTheme(newTheme, true);
 }
 
 /**
diff --git a/templates/_base.html b/templates/_base.html
@@ -2,7 +2,7 @@
 {% import "macros/index_macros.html" as index_macros %}
 
 <!doctype html>
-<html lang="en">
+<html lang="en" data-theme="{{ config.extra.theme | default(value='toggle') }}">
   <head>
     <meta http-equiv="X-UA-Compatible" content="IE=edge" />
     <meta http-equiv="content-type" content="text/html; charset=utf-8" />
@@ -143,7 +143,7 @@
     <!-- Load Fonts -->
     {% include "partials/fonts.html" %}
 
-    <!-- Pass Theme Preference as Data Attribute -->
+    <!-- Initialize theme before paint -->
     <script src="{{ get_url(path='js/init-theme.js', trailing_slash=false) | safe }}"></script>
 
     <!-- Additional scripts -->
