diff --git a/exampleSite/content/basics/branding/_index.en.md b/exampleSite/content/basics/branding/_index.en.md
index a1a9977bed..83c668d87e 100644
--- a/exampleSite/content/basics/branding/_index.en.md
+++ b/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.
diff --git a/layouts/partials/get-theme-variants.hugo b/layouts/partials/get-theme-variants.hugo
index 156c31684c..de9a35dc2e 100644
--- a/layouts/partials/get-theme-variants.hugo
+++ b/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 := "" }}
- {{- 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 }}
+ {{- $chroma := partial "get-theme-chroma.html" $themevariant.identifier }}
{{- $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 }}
\ No newline at end of file
+{{- 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 }}
\ No newline at end of file
diff --git a/layouts/partials/stylesheet.html b/layouts/partials/stylesheet.html
index eb904a106b..ded02ef864 100644
--- a/layouts/partials/stylesheet.html
+++ b/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">