feat: add default_mode theme option

Author: aksiome

docs/user_guide/customisation/light-dark.md

@@ -0,0 +1,87 @@
+# 🌗 Light and dark mode
+
+Breeze supports light and dark themes with automatic system preference detection.
+
+## Default mode
+
+Set the default theme mode via `html_theme_options` in `conf.py`:
+
+```python
+html_theme_options = {
+    "default_mode": "auto",  # "auto", "light", or "dark"
+}
+```
+
+| Value | Behavior |
+|-------|----------|
+| `auto` | Follows system preference (default) |
+| `light` | Always starts in light mode |
+| `dark` | Always starts in dark mode |
+
+Users can override this using the theme switcher, which saves their preference to localStorage.
+
+## Theme-specific content
+
+Use CSS classes to show or hide content based on the active theme.
+
+### Only in dark mode
+
+::::{tab-set}
+:::{tab-item} MyST
+````
+```{image} logo-dark.png
+:class: only-dark
+```
+````
+:::
+:::{tab-item} RST
+```rst
+.. image:: logo-dark.png
+   :class: only-dark
+```
+:::
+::::
+
+### Only in light mode
+
+::::{tab-set}
+:::{tab-item} MyST
+````
+```{image} logo-light.png
+:class: only-light
+```
+````
+:::
+:::{tab-item} RST
+```rst
+.. image:: logo-light.png
+   :class: only-light
+```
+:::
+::::
+
+### Combining both
+
+Display different images for each theme:
+
+::::{tab-set}
+:::{tab-item} MyST
+````
+```{image} logo-light.png
+:class: only-light
+```
+```{image} logo-dark.png
+:class: only-dark
+```
+````
+:::
+:::{tab-item} RST
+```rst
+.. image:: logo-light.png
+   :class: only-light
+
+.. image:: logo-dark.png
+   :class: only-dark
+```
+:::
+::::

docs/user_guide/index.md

@@ -19,5 +19,6 @@ quickstart
 customisation/announcement
 customisation/branding
 customisation/styling
+customisation/light-dark
 customisation/layout
 ```

src/sphinx_breeze_theme/theme/breeze/layout.html

@@ -17,7 +17,7 @@
 {%- block scripts -%}
   {{- script() }}
   <script data-cfasync="false">
-    const mode = localStorage.getItem("breeze-mode") || "auto";
+    const mode = localStorage.getItem("breeze-mode") || "{{ theme_default_mode }}";
     document.documentElement.dataset.mode = mode;
     if (mode === "auto") {
       const prefers = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"

src/sphinx_breeze_theme/theme/breeze/search.html

@@ -9,7 +9,7 @@
   <script defer src="{{ pathto('_static/language_data.js', 1) }}"></script>
   <script defer src="{{ pathto('searchindex.js', 1) }}"></script>
   <script data-cfasync="false">
-    const mode = localStorage.getItem("breeze-mode") || "auto";
+    const mode = localStorage.getItem("breeze-mode") || "{{ theme_default_mode }}";
     document.documentElement.dataset.mode = mode;
     if (mode === "auto") {
       const prefers = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"

src/sphinx_breeze_theme/theme/breeze/theme.conf

@@ -7,6 +7,7 @@ announcement =
 external_links =
 lang_switcher =
 version_switcher =
+default_mode = auto
 header_tabs = True
 emojis_title = False
 emojis_header_nav = False