From dbf3c8f5cded9ed9f9cbdfe1326ab7ef8f58bd4e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Benjamin=20Cab=C3=A9?= <benjamin@zephyrproject.org>
Date: Mon, 14 Oct 2024 14:36:32 +0200
Subject: [PATCH] doc: fix dark mode "flashing" on page load
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This hooks up the dark-mode-toggle-stylesheets-loader so that the dark
mode styles are loaded immediately, rather than waiting for the page to
load and then switching to dark mode. This prevents the "flashing" of
light mode styles on page load.

Fixes #79791

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
---
 doc/_templates/layout.html | 13 ++++++++++---
 doc/conf.py                |  1 -
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
index 8593fac6113..699c8ee9f36 100644
--- a/doc/_templates/layout.html
+++ b/doc/_templates/layout.html
@@ -28,7 +28,14 @@
 {% endblock %}
 {% block extrahead %}
   <meta name="color-scheme" content="dark light">
-  {# Light/Dark stylesheets added here due to https://github.com/readthedocs/sphinx_rtd_theme/issues/1100 #}
-  <link rel="stylesheet" href="{{ pathto('_static/css/light.css', 1) }}" type="text/css" media="(prefers-color-scheme: light)"/>
-  <link rel="stylesheet" href="{{ pathto('_static/css/dark.css', 1) }}" type="text/css" media="(prefers-color-scheme: dark)"/>
+  {# Use dark mode loader script to prevent "flashing" of the page on load.
+     As we need a <noscript> tag and very specific orderding of the tags, this can't be done via
+     the usual add_js_file()/add_css_file() Sphinx API.
+     See https://github.com/GoogleChromeLabs/dark-mode-toggle/issues/77 #}
+  <noscript id="dark-mode-toggle-stylesheets">
+    <link rel="stylesheet" href="{{ pathto('_static/css/light.css', 1) }}" type="text/css" media="(prefers-color-scheme: light)"/>
+    <link rel="stylesheet" href="{{ pathto('_static/css/dark.css', 1) }}" type="text/css" media="(prefers-color-scheme: dark)"/>
+  </noscript>
+  <script src="{{ pathto('_static/js/dark-mode-toggle-stylesheets-loader.min.js', 1) }}"></script>
+  <script type="module" src="{{ pathto('_static/js/dark-mode-toggle.min.mjs', 1) }}"></script>
 {% endblock %}
diff --git a/doc/conf.py b/doc/conf.py
index 17a73ec79ec..f5942acaf44 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -354,4 +354,3 @@ def setup(app):
     # theme customizations
     app.add_css_file("css/custom.css")
     app.add_js_file("js/custom.js")
-    app.add_js_file("js/dark-mode-toggle.min.mjs", type="module")