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"} ```` @@ -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 */}} {{- 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 */}} -{{- 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 */}} + {{- 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 @@ {{- $themevariants := partialCached "get-theme-variants.hugo" . }} {{- with index $themevariants 0 }} - + {{- end }}