variant: allow extended configuration #679

currently only the additional name option is recognized

assets/css/theme-auto.css

@@ -1,11 +1,11 @@
-{{- $themevariants := slice | append (.Site.Params.themeVariant | default "auto") -}}
+{{- $themevariants := partial "get-theme-variants.hugo" . -}}
 {{- $themevariantsauto := slice | append (.Site.Params.themeVariantAuto | default slice) -}}
 {{- $i := 0 -}}
 {{- if eq (int (len $themevariantsauto)) 0 -}}
 	{{- range $themevariants -}}
 		{{- $i = add $i 1 -}}
-		{{- if ne . "auto" -}}
-			{{- $themevariantsauto = $themevariantsauto | append . -}}
+		{{- if ne .identifier "auto" -}}
+			{{- $themevariantsauto = $themevariantsauto | append .identifier -}}
 			{{- break -}}
 		{{- end -}}
 	{{- end -}}
@@ -16,8 +16,8 @@
 {{- if eq (int (len $themevariantsauto)) 1 -}}
 	{{- $poppedthemevariants := last (sub (len $themevariants) $i) $themevariants -}}
 	{{- range $poppedthemevariants -}}
-		{{- if ne . "auto" -}}
-			{{- $themevariantsauto = $themevariantsauto | append . -}}
+		{{- if ne .identifier "auto" -}}
+			{{- $themevariantsauto = $themevariantsauto | append .identifier -}}
 			{{- break -}}
 		{{- end -}}
 	{{- end -}}

exampleSite/config/_default/params.toml

@@ -44,8 +44,14 @@ social.twitter = ""
 # Used color variants.
 # Default: "auto"
 # This sets one or more color variants, available to your readers to choose
-# from. You can either set a single value eg. "zen-light" or an array like
-# [ "neon", "learn" ]. If the array has more than one entry, a variant selector
+# from. You can
+# - set a single value eg. "zen-light"
+# - an array like [ "neon", "learn" ]
+# - an array with options like [ { identifier = "neon" },{ identifier = "learn" } ]
+# The last form allows to set further options for each variant.
+# The `identifier` is mandatory. You can also set `name` which overrides the
+# value displayed in the variant selector.
+# If the array has more than one entry, a variant selector
 # is shown in the lower part of the menu. The first entry in the array is the
 # default variant, used for first time visitors.
 # The theme ships with the following variants: "auto", "relearn-bright",
@@ -54,7 +60,18 @@ social.twitter = ""
 # option for themeVariantAuto below.
 # You can also define your own variants. See the docs how this works. Also,
 # the docs provide an interactive theme generator to help you with this task.
-themeVariant = [ "auto", "relearn-bright", "relearn-light", "relearn-dark", "zen-light", "zen-dark", "neon", "learn", "blue", "green", "red" ]
+themeVariant = [
+	{ identifier = "auto"          },
+	{ identifier = "relearn-light" },
+	{ identifier = "relearn-dark"  },
+	{ identifier = "zen-light"     },
+	{ identifier = "zen-dark"      },
+	{ identifier = "neon"          },
+	{ identifier = "learn"         },
+	{ identifier = "blue"          },
+	{ identifier = "green"         },
+	{ identifier = "red"           }
+]
 
 # The color variants used for auto mode.
 # Default: [ "relearn-light", "relearn-dark" ], overwritten by the first
@@ -107,7 +124,7 @@ additionalContentLanguage = [ "en" ]
 # The theme provides a mechanism to load further JavaScript and CSS
 # dependencies on demand only if they are needed. This comes in handy if you
 # want to add own shortcodes that depend on additional code to be loaded.
-# See te docs how tihs works.
+# See the docs how this works.
 # [relearn.dependencies]
 
 #++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

exampleSite/content/basics/migration/_index.en.md

@@ -22,6 +22,10 @@ This document shows you what's new in the latest release and flags it with one o
 
 - {{% badge style="note" title=" " %}}Change{{% /badge %}} The light themes have a bit more contrast for content text and headings. Also the syntaxhighlighting was changed to the more colorful MonokaiLight. This brings the syntaxhighlightning in sync with the corresponding dark theme variants, which are using Monokai.
 
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You now can configure options for every theme variant. This allows for optional extended functionality. You don't need to change anything as the old configuration options will still work (but may generate warnings now).
+
+  The extended functionality allows you to set an explicit name for a theme variant, set different colors (if you are using monochrome SVGs) or even different icons (handy if you want to adjust colors for PNGs, GIFs or JPGs) and provide an extended way to configure the automatic switch of variants based on your OS settings..
+
 ---
 
 ## 5.23.0 (2023-11-03) {#5230}
@@ -164,11 +168,7 @@ This document shows you what's new in the latest release and flags it with one o
 
 ## 5.18.0 (2023-07-27) {#5180}
 
-- {{% badge style="note" title=" " %}}Change{{% /badge %}} The theme adds additional warnings for deprecated or now unsupported features. The warnings include hints how to fix them and an additional link to the documenation.
-
-  `DEPRECATION` warnings mark features that still work but may be removed in the future.
-
-  `UNSUPPORTED` warnings mark features that will not work anymore.
+- {{% badge style="note" title=" " %}}Change{{% /badge %}} The theme adds additional warnings for deprecated or now unsupported features.
 
 - {{% badge style="note" title=" " %}}Change{{% /badge %}} There are visual improvements in displaying text links in your content aswell as to some other clickable areas in the theme. If you've overwritten some theme styles in your own CSS, keep this in mind.
 

layouts/partials/get-theme-variants.hugo

@@ -0,0 +1,13 @@
+{{- $themevariants := slice }}
+{{- $tempthemevariants := slice | append (.Site.Params.themeVariant | default "auto" ) }}
+{{- range $tempthemevariant := $tempthemevariants }}
+  {{- $themevariant := $tempthemevariant }}
+  {{- if not (reflect.IsMap $themevariant) }}
+    {{- $themevariant = dict "identifier" $tempthemevariant }}
+  {{- end }}
+  {{- if not $themevariant.name }}
+    {{- $themevariant = collections.Merge $themevariant (dict "name" ($themevariant.identifier | humanize | strings.Title)) }}
+  {{- end }}
+  {{- $themevariants = $themevariants | append $themevariant }}
+{{- end }}
+{{- return $themevariants }}

layouts/partials/menu.html

@@ -58,7 +58,7 @@
         {{- end }}
         {{- $siteLanguages := .Site.Languages }}
         {{- $showlangswitch := and .Site.IsMultiLingual (not .Site.Params.disableLanguageSwitchingButton) (gt (int (len $siteLanguages)) 1) }}
-        {{- $themevariants := slice | append (.Site.Params.themeVariant | default "auto" ) }}
+        {{- $themevariants := partial "get-theme-variants.hugo" . }}
         {{- $showvariantswitch := gt (int (len $themevariants)) 1 }}
         {{- $footer := partial "menu-footer.html" . }}
         {{- $showfooter := not (eq 0 (int (len ($footer | plainify)))) }}
@@ -103,13 +103,8 @@
                       {{- $firstvariant := true }}
                       {{- range $themevariants }}
                         {{- $themevariant := . }}
-                        {{- $variantname := replaceRE "[-_]+" " " $themevariant }}
-                        {{- if $firstvariant }}
-                          {{- $firstvariant = false }}
-                      <option id="R-{{ $themevariant }}" value="{{ $themevariant }}" selected>{{ $variantname | title }}</option>
-                        {{- else }}
-                      <option id="R-{{ $themevariant }}" value="{{ $themevariant }}">{{ $variantname | title }}</option>
-                        {{- end }}
+                      <option id="R-{{ $themevariant.identifier }}" value="{{ $themevariant.identifier }}"{{- if $firstvariant }} selected{{ end }}>{{ $themevariant.name }}</option>
+                        {{- $firstvariant = false }}
                       {{- end }}
                     </select>
                   </div>

layouts/partials/stylesheet.html

@@ -17,9 +17,9 @@
     {{- $autocss := $autotemplate | resources.ExecuteAsTemplate "css/theme-auto.css" .Site.Home }}
     {{- $c := "" }}<!-- cause Hugo to generate our theme-auto.css -->
     {{- $c = "" }}<!-- link href="{{ $autocss.RelPermalink }}{{ if $assetBusting }}?{{ now.Unix }}{{ end }}" rel="stylesheet"-->
-    {{- $themevariants := slice | append (.Site.Params.themeVariant | default "auto" ) }}
+    {{- $themevariants := partial "get-theme-variants.hugo" . }}
     {{- with index $themevariants 0 }}
-    <link href="{{(printf "css/theme-%s.css" .) | relURL}}{{ if $assetBusting }}?{{ now.Unix }}{{ end }}" rel="stylesheet" id="R-variant-style">
+    <link href="{{(printf "css/theme-%s.css" .identifier) | relURL}}{{ if $assetBusting }}?{{ now.Unix }}{{ end }}" rel="stylesheet" id="R-variant-style">
     {{- end }}
     <link href="{{"css/variant.css" | relURL}}{{ if $assetBusting }}?{{ now.Unix }}{{ end }}" rel="stylesheet">
     <link href="{{"css/print.css" | relURL}}{{ if $assetBusting }}?{{ now.Unix }}{{ end }}" rel="stylesheet" media="print">
@@ -47,7 +47,7 @@
       {{ "// variant stuff" | safeJS }}
       {{- $quotedthemevariants := slice }}
       {{- range $themevariants }}
-        {{- $quotedthemevariants = $quotedthemevariants | append (printf "'%s'" .) }}
+        {{- $quotedthemevariants = $quotedthemevariants | append (printf "'%s'" .identifier) }}
       {{- end }}
       window.variants && variants.init( [ {{ delimit $quotedthemevariants ", " | safeJS }} ] );
       {{ "// translations" | safeJS }}