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).
