theme: fix flash of non-default variant, part I #757

implements the first part, working for configured variants;

for that, loading of stylesheets was overhauled by now
merging all configured variants into one big stylesheet for
each output format and loading this instead of one stylesheet
per configured variant;

previously @media print styles were applied on top of @media screen
styles; this is now strictly isolated, which doesn't require styles
like neon to revert styles for print anymore;

this change was also used to implement the minify parameter, to shrink
those generated stylesheets, making them shrink to 66% of their
unminified size for the exampleSite;

the theme switcher functionality is now completely independend of
variant.js; the switch is now handled by in-page javascript which
avoids waiting for external scripts to load, so switching can happen
as early as possible;

switching of themes is now implemented by just setting a data attribute
to the html element, were previously a complex mechanism of dynamically
loading of variant CSS files was implemented;

the call for variant.js was removed in this changeset, making the
generator broken and useless; this will be fixed with the next patch;

assets/css/chroma-neon.css

@@ -85,5 +85,3 @@
 /* GenericTraceback */ .chroma .gt {  }
 /* GenericUnderline */ .chroma .gl {  }
 /* TextWhitespace */ .chroma .w {  }
-
-}

assets/css/format-print.css

@@ -1,8 +1,3 @@
-/* prettier-ignore {{ $assetBusting := partialCached "assetbusting.gotmpl" . -}} */
-@import '{{ printf "theme-%s.css%s" .themevariant.identifier $assetBusting }}';
-/* prettier-ignore */
-@import '{{ printf "chroma-%s.css%s" .themevariant.chroma $assetBusting }}';
-
 #R-sidebar {
   display: none;
 }
@@ -101,6 +96,7 @@ hr {
 
 #R-body #R-body-inner h1 {
   border-bottom: 1px solid rgba(221, 221, 221, 1);
+  font-size: 3.25rem;
   margin-bottom: 2rem;
   padding-bottom: 0.75rem;
 }
@@ -187,3 +183,17 @@ article {
 #R-body-inner article:first-of-type {
   break-before: avoid;
 }
+
+#R-body #R-body-inner .flex-block-wrapper {
+  max-width: calc(var(--INTERNAL-MAIN-WIDTH-MAX) - var(--INTERNAL-MENU-WIDTH-L) - 2 * 3.25rem);
+  width: 100%;
+}
+
+#R-body #R-body-inner > .flex-block-wrapper article.narrow p {
+  font-size: 1.015625rem;
+  text-align: start;
+}
+
+#R-body #R-body-inner > .flex-block-wrapper article.narrow > .article-subheading {
+  margin-top: 0;
+}

assets/css/swagger.css

@@ -1,9 +1,3 @@
-/* styles to make Swagger-UI fit into our theme */
-/* prettier-ignore {{ $assetBusting := partialCached "assetbusting.gotmpl" . -}} */
-@import '{{ printf "fonts.css%s" $assetBusting }}';
-/* prettier-ignore */
-@import '{{ printf "variables.css%s" $assetBusting }}';
-
 body {
   line-height: 1.574;
   font-variation-settings: var(--INTERNAL-MAIN-font-variation-settings);

assets/css/theme-neon.css

@@ -252,56 +252,6 @@ body .box.cstyle.transparent {
   box-shadow: none;
 }
 
-@media print {
-  #R-body h1,
-  #R-body h2,
-  #R-body h3,
-  #R-body .article-subheading,
-  #R-body h4,
-  #R-body h5,
-  #R-body h6 {
-    text-shadow: none;
-  }
-  #R-body .badge,
-  #R-body .badge > .badge-content,
-  #R-body .btn,
-  #R-body .btn > *,
-  #R-body .box,
-  #R-body .box > .box-label {
-    box-shadow: none;
-    text-shadow: none;
-  }
-  #R-body .badge.cstyle:not(.transparent),
-  #R-body .btn.cstyle {
-    --VARIABLE-BOX-TEXT-color: var(--INTERNAL-BOX-NEUTRAL-TEXT-color);
-  }
-}
-
-/* if we are in print chapter preview our @media statement from
-above will not apply, so we have to repeat it here */
-.print #R-body h1,
-.print #R-body h2,
-.print #R-body h3,
-.print #R-body .article-subheading,
-.print #R-body h4,
-.print #R-body h5,
-.print #R-body h6 {
-  text-shadow: none;
-}
-.print #R-body .badge,
-.print #R-body .badge > .badge-content,
-.print #R-body .btn,
-.print #R-body .btn > *,
-.print #R-body .box,
-.print #R-body .box > .box-label {
-  box-shadow: none;
-  text-shadow: none;
-}
-.print #R-body .badge.cstyle:not(.transparent),
-.print #R-body .btn.cstyle {
-  --VARIABLE-BOX-TEXT-color: var(--INTERNAL-BOX-NEUTRAL-TEXT-color);
-}
-
 #R-content-wrapper {
   --ps-thumb-color: rgba(208, 208, 208, 1);
   --ps-thumb-hover-color: rgba(204, 204, 204, 1);

assets/css/theme-relearn.css

@@ -1,3 +1 @@
-/* this file is here for compatiblity with older installations; use theme-relearn-light instead */
-/* prettier-ignore {{ $assetBusting := partialCached "assetbusting.gotmpl" . -}} */
-@import '{{ printf "theme-relearn-light.css%s" $assetBusting }}';
+@import 'theme-relearn-light.css';

assets/css/theme.css

@@ -1,5 +1,3 @@
-@charset "UTF-8";
-
 /* until browsers don't let us set length values based on dppx, we
 need a way to calculate them ourself */
 :root {
@@ -580,33 +578,31 @@ article a:focus > img:only-child:empty {
   max-width: calc(var(--INTERNAL-MAIN-WIDTH-MAX) - var(--INTERNAL-MENU-WIDTH-L) - 2 * 3.25rem);
   width: 100%;
 }
-
-body:not(.print) #R-body .flex-block-wrapper:has(article.narrow) {
+#R-body .flex-block-wrapper:has(article.narrow) {
   max-width: calc(var(--INTERNAL-MAIN-WIDTH-MAX) - var(--INTERNAL-MENU-WIDTH-L) - 2 * 9.75rem);
 }
-/* we limit width if we have large screens */
-body.main-width-max #R-body .flex-block-wrapper {
+.main-width-max #R-body .flex-block-wrapper {
   width: calc(var(--INTERNAL-MAIN-WIDTH-MAX) - var(--INTERNAL-MENU-WIDTH-L) - 2 * 3.25rem);
 }
-body.main-width-max:not(.print) #R-body .flex-block-wrapper:has(article.narrow) {
+.main-width-max #R-body .flex-block-wrapper:has(article.narrow) {
   width: calc(var(--INTERNAL-MAIN-WIDTH-MAX) - var(--INTERNAL-MENU-WIDTH-L) - 2 * 9.75rem);
 }
 
-body:not(.print) #R-body-inner:has(> .flex-block-wrapper article.narrow) {
+#R-body-inner:has(> .flex-block-wrapper article.narrow) {
   padding: 0 9.75rem 2rem 9.75rem;
 }
 @media screen and (max-width: 59.999rem) {
-  body:not(.print) #R-body-inner:has(> .flex-block-wrapper article.narrow) {
+  #R-body-inner:has(> .flex-block-wrapper article.narrow) {
     padding: 0 6.5rem 1rem 6.5rem;
   }
 }
 @media screen and (max-width: 47.999rem) {
-  body:not(.print) #R-body-inner:has(> .flex-block-wrapper article.narrow) {
+  #R-body-inner:has(> .flex-block-wrapper article.narrow) {
     padding: 0 3.25rem 0.375rem 3.25rem;
   }
 }
 
-body:not(.print) #R-body-inner > .flex-block-wrapper article.narrow p {
+#R-body-inner > .flex-block-wrapper article.narrow p {
   font-size: 1.2rem;
   text-align: justify;
 }
@@ -658,17 +654,17 @@ h1 {
   text-transform: uppercase;
 }
 
-body:not(.print) #R-body-inner > .flex-block-wrapper article.narrow h1 {
+#R-body-inner > .flex-block-wrapper article.narrow h1 {
   border-bottom: 4px solid rgba(134, 134, 134, 0.125);
   font-size: 3.5rem;
 }
 @media only screen and (min-width: 48rem) and (max-width: 59.999rem) {
-  body:not(.print) #R-body-inner > .flex-block-wrapper article.narrow h1 {
+  #R-body-inner > .flex-block-wrapper article.narrow h1 {
     font-size: 2.8rem;
   }
 }
 @media only screen and (max-width: 47.999rem) {
-  body:not(.print) #R-body-inner > .flex-block-wrapper article.narrow h1 {
+  #R-body-inner > .flex-block-wrapper article.narrow h1 {
     font-size: 2.5rem;
   }
 }
@@ -685,16 +681,16 @@ body:not(.print) #R-body-inner > .flex-block-wrapper article.narrow h1 {
 #R-body-inner > .flex-block-wrapper article > .article-subheading {
   margin-top: 0;
 }
-body:not(.print) #R-body-inner > .flex-block-wrapper article.narrow > .article-subheading {
+#R-body-inner > .flex-block-wrapper article.narrow > .article-subheading {
   margin-top: 2rem;
 }
 @media screen and (max-width: 59.999rem) {
-  body:not(.print) #R-body-inner > .flex-block-wrapper article.narrow > .article-subheading {
+  #R-body-inner > .flex-block-wrapper article.narrow > .article-subheading {
     margin-top: 1rem;
   }
 }
 @media screen and (max-width: 47.999rem) {
-  body:not(.print) #R-body-inner > .flex-block-wrapper article.narrow > .article-subheading {
+  #R-body-inner > .flex-block-wrapper article.narrow > .article-subheading {
     margin-top: 0.375rem;
   }
 }

exampleSite/config/_default/params.toml

@@ -75,6 +75,13 @@ themeVariant = [
 	{ identifier = 'red'            }
 ]
 
+# Minify theme assets.
+# Default: not set
+# If set to `true`, further theme asset files besides the generated HTML files
+# will be minified during build. If no value is set, the theme will avoid
+# minification if you have started with `hugo server` and otherwise will minify.
+minify = true
+
 #++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 # General
 # These options are defining general, non visual behavior.

exampleSite/config/testing/hugo.toml

@@ -19,3 +19,4 @@ disableHugoGeneratorInject = true
   disableGeneratorVersion = true
   disableAssetsBusting = true
   disableRandomIds = true
+  minify = false

exampleSite/content/configuration/sitemanagement/stableoutput/_index.en.md

@@ -1,7 +1,7 @@
 +++
 categories = ["howto"]
 description = "How to make your generated HTML output stable"
-options = ["disableAssetsBusting", "disableGeneratorVersion", "disableRandomIds"]
+options = ["disableAssetsBusting", "disableGeneratorVersion", "disableRandomIds", "minify"]
 title = "Stable Output"
 weight = 6
 +++
@@ -46,3 +46,12 @@ To turn this off, set `disableRandomIds=true`. Note, that this will result in a
 [params]
   disableRandomIds = true
 {{< /multiconfig >}}
+
+## Disabling Assets Minification
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} If `minify=true`, further theme assets will be minified during build. If no value is set, the theme will avoid minification if you have started with `hugo server` and otherwise will minify.
+
+{{< multiconfig file=hugo >}}
+[params]
+  minify = false
+{{< /multiconfig >}}

exampleSite/content/configuration/sitemanagement/stableoutput/_index.pir.md

@@ -1,7 +1,7 @@
 +++
 categories = ["howto"]
 description = "How to make your generated HTML output stable"
-options = ["disableAssetsBusting", "disableGeneratorVersion", "disableRandomIds"]
+options = ["disableAssetsBusting", "disableGeneratorVersion", "disableRandomIds", "minify"]
 title = "Stable Output"
 weight = 6
 +++

exampleSite/content/introduction/releasenotes/7/2.en.md

@@ -18,6 +18,12 @@ weight = -2
 
 ### New
 
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release fixes a long standing issue, where loading a page with a non-default variant may caused screen flashing.
+
+  Fixing this resulted in major changes how stylesheets are bundled during built and ultimately leads to different stylesheets been loaded in the browser. If you haven't done any undocumented stuff with the stylesheets, this change should not have any negative effects to your site.
+
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} As a fallout of fixing the flashing issue, you can now minify the bundled stylesheets by setting the [`minify` parameter](configuration/sitemanagement/stableoutput/#disabling-assets-minification) in your `hugo.toml`. Without configuring this parameter, the theme will minify the stylesheets for production (`hugo`) but not for development (`hugo server`).
+
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Support for Hugo’s built-in [`details` shortcode](https://gohugo.io/content-management/shortcodes/#details).
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme has updated its Mermaid dependency to 11.4.1. This adds support for [Kanban](shortcodes/mermaid#kanban) diagrams.

exampleSite/content/shortcodes/mermaid.en.md

@@ -84,6 +84,9 @@ mermaidZoom = true
 
 You can overwrite the settings by providing a JSON object in `mermaidInitialize`. See [Mermaid's documentation](https://mermaid-js.github.io/mermaid/#/Setup?id=mermaidapi-configuration-defaults) for all allowed settings.
 
+> [!NOTE]
+> Using the `theme` setting in the initialization options is unsupported. To set the theme globally edit the `--MERMAID-theme` variable of your [color variant](configuration/branding/colors/#modifying-variants).
+
 Keep in mind that initialization settings of your pages front matter overwrite all settings of your configuration options.
 
 In addition, you can merge settings for each individual graph through [diagram directives](https://mermaid-js.github.io/mermaid/#/directives?id=directives) on top of the settings of your page's front matter or configuration options.

layouts/404.html

@@ -1,6 +1,6 @@
 <!DOCTYPE html>
-{{- .Store.Set "relearnOutputFormat" "notfound" }}
-<html lang="{{ .Page.Language.LanguageCode }}" dir="{{ .Page.Language.LanguageDirection | default (T "Reading-direction") | default "ltr" }}" itemscope itemtype="http://schema.org/Article">
+{{- .Store.Set "relearnOutputFormat" "html" }}
+<html lang="{{ .Page.Language.LanguageCode }}" dir="{{ .Page.Language.LanguageDirection | default (T "Reading-direction") | default "ltr" }}" itemscope itemtype="http://schema.org/Article" data-r-output-format="{{ with .Store.Get "relearnOutputFormat" }}{{ . }}{{ else }}html{{ end }}">
   <head>
     {{- partial "meta.html" . }}
     {{- $title := partial "title.gotmpl" (dict "page" . "fullyQualified" true "reverse" true) }}
@@ -13,7 +13,7 @@
     {{- partial "stylesheet.html" . }}
     {{- partial "custom-header.html" . }}
   </head>
-  <body class="mobile-support {{ with .Store.Get "relearnOutputFormat" }}{{ . }}{{ else }}html{{ end }}" data-url="{{ partial "permalink.gotmpl" (dict "to" .) }}">
+  <body class="mobile-support {{ with .Store.Get "relearnOutputFormat" }}{{ . }}{{ else }}html{{ end }} notfound" data-url="{{ partial "permalink.gotmpl" (dict "to" .) }}">
     <div id="R-body" class="default-animation">
       <main id="R-body-inner" class="highlightable chapter" tabindex="-1">
         <div class="flex-block-wrapper">

layouts/_default/baseof.html

@@ -9,7 +9,7 @@
 {{- if .Site.Params.description }}
   {{- warnf "UNSUPPORTED usage of 'params.description' config parameter found, move it to the front matter of your home page; see https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/6/#6-0-0" }}
 {{- end }}
-<html lang="{{ .Page.Language.LanguageCode }}" dir="{{ .Page.Language.LanguageDirection | default (T "Reading-direction") | default "ltr" }}" itemscope itemtype="http://schema.org/Article">
+<html lang="{{ .Page.Language.LanguageCode }}" dir="{{ .Page.Language.LanguageDirection | default (T "Reading-direction") | default "ltr" }}" itemscope itemtype="http://schema.org/Article" data-r-output-format="{{ with .Store.Get "relearnOutputFormat" }}{{ . }}{{ else }}html{{ end }}">
   <head>
     {{- partial "meta.html" . }}
     {{- $title := partial "title.gotmpl" (dict "page" . "fullyQualified" true "reverse" true) }}