Skip to content

docs: add auto/system theme option to theme toggle #24519

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dvdksn wants to merge 6 commits into
base: main
Choose a base branch
from
+60 −40
Open

docs: add auto/system theme option to theme toggle #24519

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b8c0e3f
docs: add auto/system theme option to theme toggle (fixes #23177)
dvdksn Mar 25, 2026
1a5d9ed
fix: address docker-agent review comments on theme toggle
dvdksn Mar 25, 2026
3773425
revert: restore original contrast icon reference
dvdksn Mar 25, 2026
f8e77cd
fix: remove hidden attribute from moon and contrast icon spans
dvdksn Mar 25, 2026
2f77671
fix: add x-cloak to theme icon spans to prevent pre-Alpine flash
dvdksn Mar 25, 2026
382160d
fix: drive theme icon visibility from CSS, not Alpine, to eliminate jank
dvdksn Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 14 additions & 2 deletions assets/css/global.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,18 @@
display: none !important;
}
}
/* Theme toggle icon visibility — driven by data-theme-preference on <html>,
set synchronously by theme.js before first paint. x-show handles updates
after Alpine initialises; these rules cover the pre-Alpine window. */
:root[data-theme-preference="light"] .theme-icon-moon,
:root[data-theme-preference="light"] .theme-icon-auto,
:root[data-theme-preference="dark"] .theme-icon-sun,
:root[data-theme-preference="dark"] .theme-icon-auto,
:root[data-theme-preference="auto"] .theme-icon-sun,
:root[data-theme-preference="auto"] .theme-icon-moon {
display: none;
}

:root {
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
Expand Down Expand Up @@ -93,6 +105,6 @@ input[type="search"]::-ms-clear {
}
}

code{
font-size:0.9em;
code {
font-size: 0.9em;
}
26 changes: 8 additions & 18 deletions assets/js/theme.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,10 @@
// return 'light' or 'dark' depending on localStorage (pref) or system setting
function getThemePreference() {
const theme = localStorage.getItem("theme-preference");
if (theme) return theme;
else
return window.matchMedia("(prefers-color-scheme: dark)").matches
// update root class based on os setting or localstorage
const storedTheme = localStorage.getItem("theme-preference");
const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
document.firstElementChild.className =
storedTheme === "dark" || storedTheme === "light"
? storedTheme
: prefersDark
? "dark"
: "light";
}

// update root class based on os setting or localstorage
const preference = getThemePreference();
document.firstElementChild.className = preference === "dark" ? "dark" : "light";
localStorage.setItem("theme-preference", preference);

// set innertext for the theme switch button
// window.addEventListener("DOMContentLoaded", () => {
// const themeSwitchButton = document.querySelector("#theme-switch");
// themeSwitchButton.textContent = `${preference}_mode`;
// });
document.firstElementChild.dataset.themePreference = storedTheme || "auto";
58 changes: 38 additions & 20 deletions layouts/_partials/header.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,5 @@
<header
class="sticky top-0 z-20 h-16 w-full bg-blue-600 text-white"
>
<div
class="flex h-full justify-between gap-2 mx-auto px-4"
>
<header class="sticky top-0 z-20 h-16 w-full bg-blue-600 text-white">
<div class="mx-auto flex h-full justify-between gap-2 px-4">
<div class="flex h-full items-center gap-2 lg:gap-8">
{{- if not .IsHome }}
<button
Expand Down Expand Up @@ -45,15 +41,18 @@
</ul>
</nav>
</div>
<div id="buttons" class="flex min-w-0 items-center justify-end flex-shrink-0">
<div
id="buttons"
class="flex min-w-0 flex-shrink-0 items-center justify-end"
>
<div class="flex items-center gap-2">
<div data-tooltip-wrapper class="relative">
<button
x-data
@click="$store.gordon.toggle()"
aria-label="Ask Gordon, AI assistant"
aria-describedby="gordon-tooltip"
class="cursor-pointer flex items-center gap-2 p-2 rounded-lg bg-blue-700 border border-blue-500 text-white transition-colors focus:outline-none focus:ring focus:ring-blue-400 shimmer open-kapa-widget"
class="shimmer open-kapa-widget flex cursor-pointer items-center gap-2 rounded-lg border border-blue-500 bg-blue-700 p-2 text-white transition-colors focus:ring focus:ring-blue-400 focus:outline-none"
>
<span class="icon-svg">
{{ partial "utils/svg.html" "/icons/sparkle.svg" }}
Expand All @@ -63,35 +62,54 @@
<div
id="gordon-tooltip"
data-tooltip-body
class="absolute top-0 left-0 hidden whitespace-nowrap rounded-sm bg-gray-900 p-2 text-sm text-white"
class="absolute top-0 left-0 hidden rounded-sm bg-gray-900 p-2 text-sm whitespace-nowrap text-white"
role="tooltip"
>
Ask Gordon — AI assistant for Docker docs
<div data-tooltip-arrow class="absolute h-2 w-2 rotate-45 bg-gray-900"></div>
<div
data-tooltip-arrow
class="absolute h-2 w-2 rotate-45 bg-gray-900"
></div>
</div>
</div>

<div id="search-bar-container">
{{ partialCached "search-bar.html" "-" }}
{{ partialCached "search-bar.html" "-" }}
</div>

<button
aria-label="Theme switch"
id="theme-switch"
class="cursor-pointer p-2 rounded-lg bg-blue-700 border border-blue-500 hover:bg-blue-800 hover:border-blue-400 transition-colors focus:outline-none focus:ring focus:ring-blue-400"
x-data="{ theme: localStorage.getItem('theme-preference') }"
x-init="$watch('theme', value => {
localStorage.setItem('theme-preference', value);
document.firstElementChild.className = value;
})"
@click="theme = (theme === 'dark' ? 'light' : 'dark')"
class="cursor-pointer rounded-lg border border-blue-500 bg-blue-700 p-2 transition-colors hover:border-blue-400 hover:bg-blue-800 focus:ring focus:ring-blue-400 focus:outline-none"
x-data="{ theme: localStorage.getItem('theme-preference') || 'auto' }"
x-init="
let mql = window.matchMedia('(prefers-color-scheme: dark)');
function applyTheme(val) {
if (val === 'auto') {
localStorage.removeItem('theme-preference');
document.firstElementChild.className = mql.matches ? 'dark' : 'light';
} else {
localStorage.setItem('theme-preference', val);
document.firstElementChild.className = val;
}
document.firstElementChild.dataset.themePreference = val;
}
let handler = e => { if (theme === 'auto') document.firstElementChild.className = e.matches ? 'dark' : 'light'; };
mql.addEventListener('change', handler);
$watch('theme', val => applyTheme(val));
return () => mql.removeEventListener('change', handler);
"
@click="theme = (theme === 'light' ? 'dark' : theme === 'dark' ? 'auto' : 'light')"
>
<span class="icon-svg dark:hidden"
<span class="theme-icon-sun icon-svg" x-show="theme === 'light'"
>{{ partialCached "icon" "icons/sun.svg" "sun" }}
</span>
<span class="icon-svg hidden dark:block">
<span class="theme-icon-moon icon-svg" x-show="theme === 'dark'">
{{ partialCached "icon" "icons/moon.svg" "moon" }}
</span>
<span class="theme-icon-auto icon-svg" x-show="theme === 'auto'">
{{ partialCached "icon" "contrast" "contrast" }}
</span>
</button>
</div>
</div>
Expand Down
Loading