This is an automated email from the ASF dual-hosted git repository.

slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-fluido-skin.git

commit d0f1ab4f5279c09fdb11e66a7ec902b43b75b0da
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Tue Nov 3 00:47:58 2026 +0000

    Add a light, dark and auto theme switch
    
    Pages stay light by default, also on a system in dark mode and without 
JavaScript. A single icon button at
    the top of the menu, next to the Edit icon, shows the current mode and 
moves to the next one; the choice is
    kept for the next pages. js/fluido-theme.js, loaded in the page head so a 
stored choice applies before the
    first paint, sets Bootstrap's data-bs-theme. darkThemeEnabled makes Auto 
the default; themeSwitch false removes
    the switch.
---
 pom.xml                                            |  4 +-
 src/it/mskins-255/verify.groovy                    |  7 +-
 src/it/sidebar/verify.groovy                       | 12 ++-
 src/it/theme-switch_false/pom.xml                  | 82 +++++++++++++++++++++
 .../theme-switch_false/src/site/site.xml}          | 43 ++++++-----
 .../theme-switch_false/verify.groovy}              | 25 ++-----
 src/main/resources/META-INF/maven/site-macros.vm   | 13 +++-
 src/main/resources/META-INF/maven/site.vm          | 11 ++-
 src/main/resources/META-INF/maven/skin.xml         |  4 +
 src/main/resources/css/maven-theme.css             | 11 ++-
 src/main/resources/css/print.css                   |  1 +
 src/main/resources/js/fluido-theme.js              | 85 ++++++++++++++++++++++
 src/site/markdown/index.md.vm                      | 22 +++++-
 13 files changed, 268 insertions(+), 52 deletions(-)

diff --git a/pom.xml b/pom.xml
index fd8f506..c938f3c 100644
--- a/pom.xml
+++ b/pom.xml
@@ -135,11 +135,13 @@ under the License.
         <!-- add skin-info -->
       </resource>
 
-      <!-- include the print.css and the already minified Bootstrap 
(stylesheet and script bundle) and highlight.js bundles -->
+      <!-- include the print.css, the theme script (loaded on its own in the 
page head) and the already minified Bootstrap
+        (stylesheet and script bundle) and highlight.js bundles -->
       <resource>
         <directory>${basedir}/src/main/resources</directory>
         <includes>
           <include>css/print.css</include>
+          <include>js/fluido-theme.js</include>
           <include>css/bootstrap-${bootstrap.version}.min.css</include>
           <include>js/bootstrap-${bootstrap.version}.bundle.min.js</include>
           <include>js/highlight-${highlightjs.version}.min.js</include>
diff --git a/src/it/mskins-255/verify.groovy b/src/it/mskins-255/verify.groovy
index bff8b73..73b5325 100644
--- a/src/it/mskins-255/verify.groovy
+++ b/src/it/mskins-255/verify.groovy
@@ -18,9 +18,10 @@
  */
 
 String html = new File( basedir, "target/site/index.html" ).text
-// the dark theme is Bootstrap's dark colour mode, chosen before the first 
paint when the OS is in dark mode
-assert html.contains( "matchMedia('(prefers-color-scheme: dark)')" )
-assert html.contains( "setAttribute('data-bs-theme','dark')" )
+// the dark theme is Bootstrap's dark colour mode: Auto (follow the OS) 
becomes the default, set before the first paint
+assert html.contains( 'data-fluido-theme="auto"' )
+assert html.indexOf( 'js/fluido-theme.js' ) < html.indexOf( '</head>' )
+assert new File( basedir, "target/site/js/fluido-theme.js" ).exists()
 // no separate dark stylesheet any more
 assert !html.contains( 'dark-theme.css' )
 assert !new File( basedir, "target/site/css/dark-theme.css" ).exists()
diff --git a/src/it/sidebar/verify.groovy b/src/it/sidebar/verify.groovy
index 60481f1..35680a7 100644
--- a/src/it/sidebar/verify.groovy
+++ b/src/it/sidebar/verify.groovy
@@ -49,6 +49,13 @@ assert new File( basedir, 
"target/site/js/bootstrap-5.3.8.bundle.min.js" ).exist
 assert html.contains( '<main id="bodyColumn" class="col-lg-9 col-xl-10 
order-lg-last">' )
 assert html.contains( '<header id="leftColumn" class="col-lg-3 col-xl-2 
order-lg-first">' )
 assert html.indexOf( 'id="bodyColumn"' ) < html.indexOf( 'id="leftColumn"' )
+// the theme switch is on by default: light until the reader chooses, script 
in the head
+assert html.contains( '<button type="button" class="theme-switch btn btn-sm 
border" title="Theme" aria-label="Theme" hidden>' )
+assert html.contains( 'class="theme-icon-dark"' )
+// the switch sits in the menu, after the panel's header
+assert html.indexOf( 'class="theme-switch' ) > html.indexOf( 
'id="sidebarMenu"' )
+assert !html.contains( 'data-fluido-theme=' )
+assert html.contains( '<script src="./js/fluido-theme.js"></script>' )
 
 // wide tables scroll in their own focusable box (and stack on phones); code 
blocks are focusable too
 String deps = new File( basedir, "target/site/dependencies.html" ).text
@@ -58,6 +65,5 @@ assert html =~ /<pre tabindex="0" class="prettyprint 
linenums">/
 for ( String icon : [ 'error', 'help', 'info', 'success', 'warning' ] ) {
     assert new File( basedir, "target/site/images/icon_${icon}_sml.gif" 
).exists()
 }
-// the Edit icon sits at the top of the menu, after the panel's header
-assert html =~ /<div class="page-tools d-flex align-items-center gap-2 mb-2 
px-3"><a class="edit-link btn btn-sm border" href="[^"]+"/
-assert html.indexOf( 'class="edit-link' ) > html.indexOf( 'id="sidebarMenu"' )
+// the Edit icon sits next to the theme switch in the menu
+assert html =~ /(?s)<div class="page-tools d-flex align-items-center gap-2 
mb-2 px-3"><button type="button" class="theme-switch[^>]*>.*?<\/button>\s*<a 
class="edit-link btn btn-sm border" href="[^"]+"/
diff --git a/src/it/theme-switch_false/pom.xml 
b/src/it/theme-switch_false/pom.xml
new file mode 100644
index 0000000..8a92aff
--- /dev/null
+++ b/src/it/theme-switch_false/pom.xml
@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+   Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed with
+   this work for additional information regarding copyright ownership.
+   The ASF licenses this file to You under the Apache License, Version 2.0
+   (the "License"); you may not use this file except in compliance with
+   the License.  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"; 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
http://maven.apache.org/xsd/maven-4.0.0.xsd";>
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>org.apache.maven.skins</groupId>
+    <artifactId>maven-skins</artifactId>
+    <version>@project.parent.version@</version>
+  </parent>
+
+  <groupId>org.apache.maven.skins.its</groupId>
+  <artifactId>@project.artifactId@-theme-switch_false</artifactId>
+  <version>@project.version@</version>
+
+  <name>@project.name@ IT, theme switch disabled</name>
+  
<url>https://maven.apache.org/skins/@project.artifactId@/theme-switch_false/</url>
+
+  <properties>
+    <skinName>@project.name@</skinName>
+    <skinDescription>@project.description@</skinDescription>
+    <skinGroupId>@project.groupId@</skinGroupId>
+    <skinArtifactId>@project.artifactId@</skinArtifactId>
+    <skinVersion>@project.version@</skinVersion>
+  </properties>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-site-plugin</artifactId>
+        <version>@sitePluginVersion@</version>
+      </plugin>
+    </plugins>
+  </build>
+
+  <reporting>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-project-info-reports-plugin</artifactId>
+        <version>@projectInfoReportsPluginVersion@</version>
+        <configuration>
+          <dependencyDetailsEnabled>false</dependencyDetailsEnabled>
+        </configuration>
+        <reportSets>
+          <reportSet>
+            <reports>
+              <report>index</report>
+              <report>summary</report>
+              <report>licenses</report>
+              <report>team</report>
+              <report>scm</report>
+              <report>issue-management</report>
+              <report>mailing-lists</report>
+              <report>dependencies</report>
+              <report>ci-management</report>
+              <report>plugin-management</report>
+              <report>plugins</report>
+            </reports>
+          </reportSet>
+        </reportSets>
+      </plugin>
+    </plugins>
+  </reporting>
+
+</project>
diff --git a/src/main/resources/css/print.css 
b/src/it/theme-switch_false/src/site/site.xml
similarity index 53%
copy from src/main/resources/css/print.css
copy to src/it/theme-switch_false/src/site/site.xml
index 3f86a93..b5ce6f9 100644
--- a/src/main/resources/css/print.css
+++ b/src/it/theme-switch_false/src/site/site.xml
@@ -1,3 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
 /*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
@@ -16,23 +19,27 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+ -->
+
+<site xmlns="http://maven.apache.org/SITE/2.0.0"; 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+  xsi:schemaLocation="http://maven.apache.org/SITE/2.0.0 
https://maven.apache.org/xsd/site-2.0.0.xsd";
+  name="${skinName}">
+
+  <skin>
+    <groupId>${skinGroupId}</groupId>
+    <artifactId>${skinArtifactId}</artifactId>
+    <version>${skinVersion}</version>
+  </skin>
 
-#banner,
-#topbar,
-footer,
-.menu-toggle,
-#footer,
-#leftcol,
-#breadcrumbs,
-.docs #toc,
-.docs .courtesylinks,
-#leftColumn,
-#navColumn {
-  display: none !important;
-}
+  <body>
+    <breadcrumbs>
+      <item name="Apache Maven Fluido Skin"  
href="https://maven.apache.org/skins/maven-fluido-skin/index.html"; />
+    </breadcrumbs>
+  </body>
 
-#bodyColumn,
-body.docs div.docs {
-  margin: 0 !important;
-  border: none !important;
-}
+  <custom>
+    <fluidoSkin>
+      <themeSwitch>false</themeSwitch>
+    </fluidoSkin>
+  </custom>
+</site>
diff --git a/src/main/resources/css/print.css 
b/src/it/theme-switch_false/verify.groovy
similarity index 70%
copy from src/main/resources/css/print.css
copy to src/it/theme-switch_false/verify.groovy
index 3f86a93..7f7fa0e 100644
--- a/src/main/resources/css/print.css
+++ b/src/it/theme-switch_false/verify.groovy
@@ -7,7 +7,7 @@
  * "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
  *
- *   http://www.apache.org/licenses/LICENSE-2.0
+ *  http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
@@ -17,22 +17,9 @@
  * under the License.
  */
 
-#banner,
-#topbar,
-footer,
-.menu-toggle,
-#footer,
-#leftcol,
-#breadcrumbs,
-.docs #toc,
-.docs .courtesylinks,
-#leftColumn,
-#navColumn {
-  display: none !important;
-}
+String html = new File( basedir, "target/site/index.html" ).text
 
-#bodyColumn,
-body.docs div.docs {
-  margin: 0 !important;
-  border: none !important;
-}
+// themeSwitch false: no switch and no theme script, so the page stays light
+assert !html.contains( 'theme-switch' )
+assert !html.contains( 'fluido-theme.js' )
+assert !html.contains( 'data-bs-theme' )
diff --git a/src/main/resources/META-INF/maven/site-macros.vm 
b/src/main/resources/META-INF/maven/site-macros.vm
index 04d78fd..050d8d0 100644
--- a/src/main/resources/META-INF/maven/site-macros.vm
+++ b/src/main/resources/META-INF/maven/site-macros.vm
@@ -465,11 +465,20 @@ Apache Maven Doxia Site Renderer#if( 
$doxiaSiteRendererVersion ) $doxiaSiteRende
 #end
 ##
 ##
+## the colour theme switch: one icon button showing the current mode, shown by 
fluido-theme.js
+#macro( themeSwitch )
+<button type="button" class="theme-switch btn btn-sm border" title="Theme" 
aria-label="Theme" hidden>##
+<svg class="theme-icon-light" width="16" height="16" viewBox="0 0 16 16" 
aria-hidden="true"><circle cx="8" cy="8" r="3" fill="currentColor"/><path d="M8 
1v1.5M8 13.5V15M1 8h1.5M13.5 8H15M3.05 3.05l1.06 1.06M11.89 11.89l1.06 
1.06M3.05 12.95l1.06-1.06M11.89 4.11l1.06-1.06" stroke="currentColor" 
stroke-width="1.5" stroke-linecap="round"/></svg>##
+<svg class="theme-icon-dark" width="16" height="16" viewBox="0 0 16 16" 
aria-hidden="true"><path d="M6.2 1.2a6.9 6.9 0 1 0 8.6 8.6A5.6 5.6 0 0 1 6.2 
1.2z" fill="currentColor"/></svg>##
+<svg class="theme-icon-auto" width="16" height="16" viewBox="0 0 16 16" 
aria-hidden="true"><circle cx="8" cy="8" r="6.25" fill="none" 
stroke="currentColor" stroke-width="1.5"/><path d="M8 1.75a6.25 6.25 0 0 0 0 
12.5z" fill="currentColor"/></svg>##
+</button>##
+#end
 ##
-## the page tools: for an editable page, an Edit link to its source
+## the page tools: the theme switch and, for an editable page, an Edit link to 
its source
 #macro( pageTools $cssClass )
-#**##if( $editHref )
+#**##if( $themeSwitch || $editHref )
 <div class="page-tools d-flex align-items-center gap-2 $cssClass">##
+#*  *##if( $themeSwitch )#themeSwitch()#end##
 #*  *##if( $editHref )<a class="edit-link btn btn-sm border" href="$editHref" 
title="$text.get( "template.edit" )" aria-label="$text.get( "template.edit" 
)"><svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path 
d="M11.2 1.8l3 3L5.4 13.6 1.8 14.2l.6-3.6z" fill="none" stroke="currentColor" 
stroke-width="1.5" stroke-linejoin="round"/><path d="M9.4 3.6l3 3" 
stroke="currentColor" stroke-width="1.5"/></svg></a>#end##
 </div>
 #**##end
diff --git a/src/main/resources/META-INF/maven/site.vm 
b/src/main/resources/META-INF/maven/site.vm
index 7d3b0a6..3cbabd3 100644
--- a/src/main/resources/META-INF/maven/site.vm
+++ b/src/main/resources/META-INF/maven/site.vm
@@ -29,7 +29,10 @@
  | Rendered using Apache Maven Fluido Skin @project.version@
 -->
 ##
-<html xmlns="http://www.w3.org/1999/xhtml"; lang="#if ( $locale.toString() 
)$locale.toLanguageTag()#{else}en#end">
+## colour theme: light by default; darkThemeEnabled makes Auto (follow the OS) 
the default; themeSwitch adds the switch
+#set( $darkThemeEnabled = $convert.toBoolean( $site.getCustomValue( 
'fluidoSkin.darkThemeEnabled', 'false' ) ) )
+#set( $themeSwitch = $convert.toBoolean( $site.getCustomValue( 
'fluidoSkin.themeSwitch', 'true' ) ) )
+<html xmlns="http://www.w3.org/1999/xhtml"; lang="#if ( $locale.toString() 
)$locale.toLanguageTag()#{else}en#end"#if( $darkThemeEnabled ) 
data-fluido-theme="auto"#end>
   <head>
     <meta charset="${outputEncoding}" />
 ## the page head may not declare a second charset; its viewport and generator 
replace the skin's own
@@ -51,9 +54,9 @@
     <title>$esc.xml( $title )</title>
     <link rel="stylesheet" 
href="$relativePath/css/[email protected][email protected]" />
     <link rel="stylesheet" 
href="$relativePath/css/[email protected][email protected]" />
-## darkThemeEnabled: follow a dark colour scheme of the OS through Bootstrap's 
colour modes, before the first paint
-#if( $convert.toBoolean( $site.getCustomValue( 'fluidoSkin.darkThemeEnabled', 
'false' ) ) )
-    <script>if(window.matchMedia&&window.matchMedia('(prefers-color-scheme: 
dark)').matches){document.documentElement.setAttribute('data-bs-theme','dark');}</script>
+## sets Bootstrap's colour mode before the first paint; without it the page 
stays light
+#if( $themeSwitch || $darkThemeEnabled )
+    <script src="$relativePath/js/fluido-theme.js"></script>
 #end
     <link rel="stylesheet" href="$relativePath/css/site.css" />
     <link rel="stylesheet" href="$relativePath/css/print.css" media="print" />
diff --git a/src/main/resources/META-INF/maven/skin.xml 
b/src/main/resources/META-INF/maven/skin.xml
index 76dd38c..07b5628 100644
--- a/src/main/resources/META-INF/maven/skin.xml
+++ b/src/main/resources/META-INF/maven/skin.xml
@@ -34,6 +34,10 @@ under the License.
       <resource-name>css/gh-fork-ribbon.min.css</resource-name>
       <vtl-condition><![CDATA[#if( $site.getCustomChild( 
'fluidoSkin.gitHub.projectId' ) )true#end]]></vtl-condition>
     </resource-condition>
+    <resource-condition>
+      <resource-name>js/fluido-theme.js</resource-name>
+      <vtl-condition><![CDATA[#if( !$site.getCustomValue( 
'fluidoSkin.themeSwitch', 'true' ).equalsIgnoreCase( 'false' ) || 
$site.getCustomValue( 'fluidoSkin.darkThemeEnabled', 'false' 
).equalsIgnoreCase( 'true' ) )true#end]]></vtl-condition>
+    </resource-condition>
     <resource-condition>
       <resource-name>images/profiles/pre-release.png</resource-name>
       <vtl-condition><![CDATA[#if( $site.getCustomValue( 'fluidoSkin.profile', 
'' ).equalsIgnoreCase( 'pre-release' ) )true#end]]></vtl-condition>
diff --git a/src/main/resources/css/maven-theme.css 
b/src/main/resources/css/maven-theme.css
index a74f00c..f958f0e 100644
--- a/src/main/resources/css/maven-theme.css
+++ b/src/main/resources/css/maven-theme.css
@@ -35,10 +35,19 @@ pre {
 
 /* banner and logo images and Mermaid diagrams (sitetools initialises Mermaid 
with its light theme) are drawn for a
    white page: in the dark colour mode they keep a white card */
-/* the Edit icon */
+/* the theme switch shows the icon of the current mode */
+.theme-switch,
 .edit-link {
   line-height: 1;
 }
+.theme-switch svg {
+  display: none;
+}
+.theme-switch[data-fluido-theme-mode=light] .theme-icon-light,
+.theme-switch[data-fluido-theme-mode=dark] .theme-icon-dark,
+.theme-switch[data-fluido-theme-mode=auto] .theme-icon-auto {
+  display: inline;
+}
 
 /* a logo with a dark-theme sibling swaps to it in the dark colour mode */
 .banner-dark,
diff --git a/src/main/resources/css/print.css b/src/main/resources/css/print.css
index 3f86a93..1de2de3 100644
--- a/src/main/resources/css/print.css
+++ b/src/main/resources/css/print.css
@@ -21,6 +21,7 @@
 #topbar,
 footer,
 .menu-toggle,
+.theme-switch,
 #footer,
 #leftcol,
 #breadcrumbs,
diff --git a/src/main/resources/js/fluido-theme.js 
b/src/main/resources/js/fluido-theme.js
new file mode 100644
index 0000000..c94f7d9
--- /dev/null
+++ b/src/main/resources/js/fluido-theme.js
@@ -0,0 +1,85 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/* Colour theme. Pages are light by default, and stay light without this 
script. It maps the reader's choice onto
+   Bootstrap's colour modes (data-bs-theme on <html>): Light, Dark, or Auto, 
which follows the OS colour scheme.
+   darkThemeEnabled makes Auto the default (data-fluido-theme="auto" on 
<html>). The choice is kept in localStorage.
+   Loaded in <head>, so a stored choice applies before the first paint. It 
shows the switch that site.vm puts,
+   hidden, at the top of the menu: one icon button that cycles the modes. 
Plain ES5. */
+( function() {
+    var KEY = 'fluido-theme';
+    var MODES = [ 'light', 'dark', 'auto' ];
+    var root = document.documentElement;
+    var osDark = window.matchMedia ? window.matchMedia( 
'(prefers-color-scheme: dark)' ) : null;
+    var fallback = root.getAttribute( 'data-fluido-theme' ) === 'auto' ? 
'auto' : 'light';
+
+    function stored() {
+        try {
+            var mode = localStorage.getItem( KEY );
+            return MODES.indexOf( mode ) >= 0 ? mode : fallback;
+        } catch ( e ) {
+            return fallback; // storage blocked
+        }
+    }
+
+    var current = stored();
+
+    function apply() {
+        var dark = current === 'dark' || ( current === 'auto' && osDark !== 
null && osDark.matches );
+        root.setAttribute( 'data-bs-theme', dark ? 'dark' : 'light' );
+    }
+
+    apply();
+    if ( osDark ) {
+        if ( osDark.addEventListener ) {
+            osDark.addEventListener( 'change', apply );
+        } else if ( osDark.addListener ) {
+            osDark.addListener( apply );
+        }
+    }
+
+    var LABELS = { light: 'Light', dark: 'Dark', auto: 'Auto' };
+
+    // the page carries the switch, one icon button hidden until this script 
can make it work: it shows the current
+    // mode's icon and moves to the next mode on each activation
+    document.addEventListener( 'DOMContentLoaded', function() {
+        var button = document.querySelector( '.theme-switch' );
+        if ( !button ) {
+            return;
+        }
+        function show() {
+            var next = MODES[ ( MODES.indexOf( current ) + 1 ) % MODES.length 
];
+            button.setAttribute( 'data-fluido-theme-mode', current );
+            button.title = 'Theme: ' + LABELS[ current ];
+            button.setAttribute( 'aria-label', 'Theme: ' + LABELS[ current ] + 
'. Activate for ' + LABELS[ next ] + '.' );
+        }
+        button.addEventListener( 'click', function() {
+            current = MODES[ ( MODES.indexOf( current ) + 1 ) % MODES.length ];
+            try {
+                localStorage.setItem( KEY, current );
+            } catch ( e ) {
+                // not stored: the choice lasts for this page only
+            }
+            apply();
+            show();
+        } );
+        show();
+        button.hidden = false;
+    } );
+} )();
diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm
index 445135b..8cbe42a 100644
--- a/src/site/markdown/index.md.vm
+++ b/src/site/markdown/index.md.vm
@@ -483,7 +483,12 @@ Since version **1\.3\.1**, you can configure the 
breadcrumb divider (default is
 
 ${esc.h}${esc.h}${esc.h} <a id="Dark_Theme"></a>Dark Theme
 
-Since version **2\.2\.0**, you can enable a dark theme, which activates based 
on the browser preferences through Bootstrap's dark colour mode:
+Pages are light by default. A theme switch in the breadcrumbs bar lets the 
reader choose Light, Dark or Auto (follows
+the operating system) and keeps the choice for the next pages; it maps the 
choice onto Bootstrap's colour modes. Without
+JavaScript the switch does not show and pages stay light.
+
+With `darkThemeEnabled` (since **2\.2\.0**), Auto is the default, so the dark 
theme activates based on the browser
+preferences until the reader chooses otherwise:
 
 ```xml
 <site xmlns="http://maven.apache.org/SITE/2.0.0"; 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
@@ -498,6 +503,21 @@ Since version **2\.2\.0**, you can enable a dark theme, 
which activates based on
 </site>
 ```
 
+To remove the switch, set `themeSwitch` to `false`:
+
+```xml
+<site xmlns="http://maven.apache.org/SITE/2.0.0"; 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+  xsi:schemaLocation="http://maven.apache.org/SITE/2.0.0 
https://maven.apache.org/xsd/site-2.0.0.xsd";>
+  [...]
+  <custom>
+    <fluidoSkin>
+      <themeSwitch>false</themeSwitch>
+    </fluidoSkin>
+  </custom>
+  [...]
+</site>
+```
+
 # Acknowledgment
 
 ${project.name} contains/redistributes [Bootstrap](https://getbootstrap.com/), 
released under the [MIT 
License](https://github.com/twbs/bootstrap/blob/main/LICENSE).

Reply via email to