variant: allow @import in own stylesheets #679

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

@@ -18,7 +18,7 @@ Once configured in your `config.toml`, you can select them with the variant sele
 
 Set the `themeVariant` value to the name of your theme file. That's it! Your site will be displayed in this variant only.
 
-````toml
+````toml {title="config.toml"}
 [params]
   themeVariant = "relearn-light"
 ````
@@ -34,7 +34,7 @@ If you want to make changes to a shipped color variant, create a copy in your si
 
 You can also set multiple variants. In this case, the first variant is the default chosen on first view and a variant selector will be shown in the menu footer if the array contains more than one entry.
 
-````toml
+````toml {title="config.toml"}
 [params]
   themeVariant = [ "relearn-light", "relearn-dark" ]
 ````
@@ -51,7 +51,7 @@ You can also cause the site to adjust to your OS settings for light/dark mode. J
 
 You can use the `auto` value with the single or multiple variants option. If you are using multiple variants, you can drop `auto` at any position in the option's array, but usually it makes sense to set it in the first position and make it the default.
 
-````toml
+````toml {title="config.toml"}
 [params]
   themeVariant = [ "auto", "red" ]
 ````
@@ -62,7 +62,7 @@ In the above example, you would end with `red` for light mode and the default of
 
 If you don't like that behavior, you can explicitly set `themeVariantAuto`. The first entry in the array is the color variant for light mode, the second for dark mode.
 
-````toml
+````toml {title="config.toml"}
 [params]
   themeVariantAuto = [ "learn", "neon" ]
 ````
@@ -77,7 +77,7 @@ If no favicon file is found, the theme will lookup the alternative filename `log
 
 If you need to change this default behavior, create a new file `layouts/partials/favicon.html` in your site's directory and write something like this:
 
-````html
+````html {title="layouts/partials/favicon.html"}
 <link rel="icon" href="/images/favicon.bmp" type="image/bmp">
 ````
 
@@ -105,14 +105,14 @@ Like with the [multiple variants](#multiple-variants) option, you are defining y
 
 Again, in this case, the first variant is the default chosen on first view and a variant selector will be shown in the menu footer if the array contains more than one entry.
 
-````toml
+````toml {title="config.toml"}
 [params]
   themeVariant = [ "relearn-light", "relearn-dark" ]
 ````
 
 you now write it that way:
 
-````toml
+````toml {title="config.toml"}
 [params]
   [[params.themeVariant]]
     identifier = "relearn-light"
@@ -132,7 +132,7 @@ The `identifier` option is mandatory and equivalent to the string in the first e
 
 ### Example Configuration of This Site
 
-````toml
+````toml {title="config.toml"}
 [params]
   [[params.themeVariant]]
     identifier = "relearn-auto"
@@ -153,3 +153,36 @@ The `identifier` option is mandatory and equivalent to the string in the first e
   [[params.themeVariant]]
     identifier = "neon"
 ````
+
+## Modify Shipped Variants
+
+In case you like a shipped variant but only want to tweak some aspects, you have two choices:
+
+1. Copy and change
+
+    You can copy the shipped variant file from the theme's `static/css` directory to the site's `static/css` directory and either store it with the same name or give it a new name. Edit the settings and save the new file. Afterwards you can use it in your `config.toml` by the choosen name.
+
+2. Create and import
+
+    You can create a new variant file in the site's `static/css` directory and give it a new name. Import the shipped variant, add the settings you want to change and save the new file. Afterwards you can use it in your `config.toml` by the choosen name.
+
+    For example, you want to use the `relearn-light` variant but want to change the syntax highlightning schema to the one used in the `neon` variant. For that, create a new `static/css/theme-my-branding.css` in your site's directory and add the following lines:
+
+    ````css {title="static/css/theme-my-branding.css"}
+    @import "theme-relearn-light.css";
+
+    :root {
+      --CODE-theme: learn; /* name of the chroma styleheet file */
+      --CODE-BLOCK-color: rgba( 226, 228, 229, 1 ); /* fallback color for code text */
+      --CODE-BLOCK-BG-color: rgba( 40, 42, 54, 1 ); /* fallback color for code background */
+    }
+    ````
+
+    Afterwards put this in your `config.toml` to use your new variant:
+
+    ````toml {title="config.toml"}
+    [params]
+      themeVariant = "my-branding"
+    ````
+
+    In comparison to _copy and change_, this has the advantage that you profit from any adjustments to the `relearn-light` variant but keep your modifications.

layouts/partials/get-theme-variants.hugo

@@ -48,28 +48,8 @@ Non-auto run
 {{- range $tempthemevariant := $tempthemevariants }}
   {{- $themevariant := $tempthemevariant }}
   {{- if not (collections.IsSet $themevariant "auto") }}
-    {{- $themecontent := "" }}
+    {{- $chroma := partial "get-theme-chroma.html" $themevariant.identifier }}
-    {{- with resources.Get (printf "css/theme-%s.css" $themevariant.identifier) }}
-      {{- $themecontent = .Content}}
-    {{- else }}
-      {{- $themecontent = readFile (printf "static/css/theme-%s.css" $themevariant.identifier) }}
-    {{- end }}
-    {{- $chroma := "" }}
-    {{- range findRESubmatch `[ \t]*--CODE-theme\s*:\s*([^;]*?)\s*;` $themecontent 1 }}
-      {{- $chroma = index . 1 }}
-    {{- else }}
-      {{- range findRESubmatch `[ \t]*@import\s+[^$]*?chroma-([^.]*?)\.css` $themecontent 1 }}
-        {{- $chroma = index . 1 }}
-        {{- warnf "\"theme-%s.css\": DEPRECATED use of @import for chroma stylesheet, instead use '--CODE-theme: %s;'" $themevariant.identifier $chroma }}
-        {{- $themecontent = replaceRE `[ \t]*@import\s+[^$]*?chroma-[^.]*?\.css.*?\n` "" $themecontent }}
-      {{- else }}
-        {{- $chroma = "relearn-light" }}
-      {{- end }}
-      {{- $themecontent = replaceRE `(:root\s*\{[ \t]*)(\s*)` (printf "${1}${2}--CODE-theme: %s;${2}" $chroma) $themecontent }}
-    {{- end }}
     {{- $themevariant = collections.Merge $themevariant (dict "chroma" $chroma) }}
-    {{- $cssres := $themecontent | resources.FromString (printf "css/theme-%s.css" $themevariant.identifier) }}
-    {{- /* the following code causes Hugo to generate our css file - although it is in comments */}}<!-- {{ $cssres.RelPermalink }} -->
   {{- end }}
   {{- $themevariants = $themevariants | append $themevariant }}
 {{- end }}
@@ -127,4 +107,39 @@ Auto run
 {{- $cssres := $printres | resources.ExecuteAsTemplate "css/format-print.css" (index (collections.Where $themevariants "identifier" "relearn-light") 0) }}
 {{- /* the following code causes Hugo to generate our css file - although it is in comments */}}<!-- {{ $cssres.RelPermalink }} -->
 
-{{- return collections.Where $tempthemevariants "config" true }}
+{{- return collections.Where $themevariants "config" true }}
+
+{{ define "partials/get-theme-chroma.html" }}
+  {{- $identifier := . }}
+  {{- $themecontent := "" }}
+  {{- with resources.Get (printf "css/theme-%s.css" $identifier) }}
+    {{- $themecontent = .Content}}
+  {{- else }}
+    {{- if fileExists (printf "static/css/theme-%s.css" $identifier) }}
+      {{- $themecontent = readFile (printf "static/css/theme-%s.css" $identifier) }}
+    {{- else }}
+      {{- errorf "\"theme-%s.css\": file not found neither in \"static/css\" and \"assets/css\"" $identifier }}
+    {{- end }}
+  {{- end }}
+  {{- $chroma := "" }}
+  {{- range findRESubmatch `[ \t]*--CODE-theme\s*:\s*([^;]*?)\s*;` $themecontent }}
+    {{- $chroma = index . 1 }}
+  {{- else }}
+    {{- range findRESubmatch `[ \t]*@import\s+[^$]*?chroma-([^.]*?)\.css` $themecontent }}
+      {{- $chroma = index . 1 }}
+      {{- warnf "\"theme-%s.css\": DEPRECATED use of @import for chroma stylesheet, instead use '--CODE-theme: %s;'" $identifier $chroma }}
+      {{- $themecontent = replaceRE `[ \t]*@import\s+[^$]*?chroma-[^.]*?\.css.*?\n` "" $themecontent }}
+    {{- else }}
+      {{- range findRESubmatch `[ \t]*@import\s+[^$]*?theme-([^.]*?)\.css` $themecontent }}
+        {{- $subidentifier := index . 1 }}
+        {{- $chroma = partial "get-theme-chroma.html" $subidentifier }}
+      {{- else }}
+        {{- $chroma = "relearn-light" }}
+      {{- end }}
+    {{- end }}
+    {{- $themecontent = replaceRE `(:root\s*\{[ \t]*)(\s*)` (printf "${1}${2}--CODE-theme: %s;${2}" $chroma) $themecontent }}
+  {{- end }}
+  {{- $cssres := $themecontent | resources.FromString (printf "css/theme-%s.css" $identifier) }}
+  {{- /* the following code causes Hugo to generate our css file - although it is in comments */}}<!-- {{ $cssres.RelPermalink }} -->
+  {{- return $chroma }}
+{{- end }}

layouts/partials/stylesheet.html

@@ -15,8 +15,8 @@
     <link href="{{"css/theme.css" | relURL}}{{ if $assetBusting }}?{{ now.Unix }}{{ end }}" rel="stylesheet">
     {{- $themevariants := partialCached "get-theme-variants.hugo" . }}
     {{- with index $themevariants 0 }}
-    <link href="{{(printf "css/chroma-%s.css" .chroma) | safeHTML | relURL}}{{ if $assetBusting }}?{{ now.Unix }}{{ end }}" rel="stylesheet" id="R-variant-chroma-style">
     <link href="{{(printf "css/theme-%s.css" .identifier) | relURL}}{{ if $assetBusting }}?{{ now.Unix }}{{ end }}" rel="stylesheet" id="R-variant-style">
+    <link href="{{(printf "css/chroma-%s.css" .chroma) | safeHTML | relURL}}{{ if $assetBusting }}?{{ now.Unix }}{{ end }}" rel="stylesheet" id="R-variant-chroma-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">