Brrrand'n

Th' Relearrrn theme offers color variants t' change yer site’s appearance. Each color variant contains o' a CSS file an' optional sett'ns 'n yer hugo.toml.

Ye can use th' shipped variants, cust'mize them, or create yer own. Th' interactive variant generator can help ye wit' this.

Once set up 'n hugo.toml, ye can switch variants us'n th' selector at th' bottom o' th' menu.

Shipped Variants

Th' theme ships wit' th' follow'n set o' variants

• Relearrrn
  • Light: th' classic Relearrrn default, com'n wit' signature green, dark sidebar an' light rrrambl'n area
  • Dark: dark variant o' Light, com'n wit' signature green, dark sidebar an' dark rrrambl'n area
  • Bright: alternative o' Light, com'n wit' signature green, green sidebar an' light rrrambl'n area
• Zen
  • Light: a more relaxed white/grey variant, com'n wit' blue accents, light sidebar an' light rrrambl'n area
  • Dark: dark variant o' Light, com'n wit' blue accents, dark sidebar an' dark rrrambl'n area
• Contrast
  • Light: colors chosen fer high contrast, com'n wit' black text on white, darker boxes an' a match'n rules highlight'n
  • Dark: dark variant o' Light, com'n wit' white text on black, brighter boxes an' a match'n rules highlight'n
• Experimental
  • Neon: a variant that glows 'n th' dark, gradient sidebar an' dark rrrambl'n area
• Retro
  • Learrrn: th' default o' th' old Learrrn theme, com'n wit' signature light purple, dark sidebar an' light rrrambl'n area
  • Blue: a blue variant o' th' old Learrrn theme, com'n tinted 'n blue, dark sidebar an' light rrrambl'n area
  • Green: a green variant o' th' old Learrrn theme, com'n tinted 'n green, dark sidebar an' light rrrambl'n area
  • Red: a red variant o' th' old Learrrn theme, com'n tinted 'n red, dark sidebar an' light rrrambl'n area

Chang'n th' Variant

Opt'n Set th' themeVariant option t' change th' variant.

Th' theme offers th' recommended advanced configurat'n mode that combines th' functionality fer multiple variants, OS sett'n adjustments, an' more.

Simple Setup

Single Variant

Set themeVariant t' yer theme CSS file name:

[params]
  themeVariant = 'relearn-light'

params:
  themeVariant: relearn-light

{
   "params": {
      "themeVariant": "relearn-light"
   }
}

Place yer theme file 'n assets/css or themes/hugo-theme-relearn/assets/css. Name it theme-*.css.

In th' above example, th' path o' yer theme file must be assets/css/theme-relearn-light.css or themes/hugo-theme-relearn/assets/css/theme-relearn-light.css.

Multiple Variants

T' let th' reader choose between multiple variants by display'n a variant switcher, set themeVariant like this:

[params]
  themeVariant = ['relearn-light', 'relearn-dark']

params:
  themeVariant:
  - relearn-light
  - relearn-dark

{
   "params": {
      "themeVariant": [
         "relearn-light",
         "relearn-dark"
      ]
   }
}

Th' first variant be th' default, an' a selector will appear if there’s more than one.

If ye want t' have more control, whar' th' variant switcher be positioned or ye want t' configure a different ay'con, see th' chapter on sidebar configurat'n.

Adjust t' OS Sett'ns

Use th' auto value t' match OS light/dark sett'ns. Usually it makes sense t' set it 'n th' first posit'n an' make it th' default.

[params]
  themeVariant = ['auto', 'red']

params:
  themeVariant:
  - auto
  - red

{
   "params": {
      "themeVariant": [
         "auto",
         "red"
      ]
   }
}

If ye don’t configure anyth'n else, th' theme will default t' use relearn-light fer light mode an' relearn-dark fer dark mode.

Default be relearn-light fer light an' relearn-dark fer dark mode. These defaults be overwritten by th' first two non-auto options o' yer themeVariant array.

Ye can override th' default wit' themeVariantAuto:

[params]
  themeVariantAuto = ['learn', 'neon']

params:
  themeVariantAuto:
  - learn
  - neon

{
   "params": {
      "themeVariantAuto": [
         "learn",
         "neon"
      ]
   }
}

Advanced

Th' theme offers an advanced way t' configure theme variants an' all o' th' aspects above inside o' a single configurat'n item. This comes wit' some features previously unsupported.

Like wit' th' multiple variants option, ye be defin'n yer theme variants 'n an array but now 'n a table wit' suboptions.

Again, 'n this case, th' first variant be th' default chosen on first view an' a variant selector will be shown 'n th' menu footer if th' array contains more than one entry.

[params]
  themeVariant = ['relearn-light', 'relearn-dark']

params:
  themeVariant:
  - relearn-light
  - relearn-dark

{
   "params": {
      "themeVariant": [
         "relearn-light",
         "relearn-dark"
      ]
   }
}

ye now write it that way:

[params]
  [[params.themeVariant]]
    identifier = 'relearn-light'

  [[params.themeVariant]]
    identifier = 'relearn-dark'

params:
  themeVariant:
  - identifier: relearn-light
  - identifier: relearn-dark

{
   "params": {
      "themeVariant": [
         {
            "identifier": "relearn-light"
         },
         {
            "identifier": "relearn-dark"
         }
      ]
   }
}

Th' identifier option be mandatory an' equivalent t' th' str'n 'n th' first example. Further options can be configured, see th' table below.

Parameters

Example Configurat'n

[params]
  [[params.themeVariant]]
    auto = []
    identifier = 'relearn-auto'
    name = 'Relearn Light/Dark'

  [[params.themeVariant]]
    identifier = 'relearn-light'

  [[params.themeVariant]]
    identifier = 'relearn-dark'

  [[params.themeVariant]]
    identifier = 'relearn-bright'

  [[params.themeVariant]]
    auto = ['zen-light', 'zen-dark']
    identifier = 'zen-auto'
    name = 'Zen Light/Dark'

  [[params.themeVariant]]
    identifier = 'zen-light'

  [[params.themeVariant]]
    identifier = 'zen-dark'

  [[params.themeVariant]]
    auto = ['learn', 'neon']
    identifier = 'retro-auto'
    name = 'Retro Learn/Neon'

  [[params.themeVariant]]
    identifier = 'neon'

  [[params.themeVariant]]
    identifier = 'learn'

params:
  themeVariant:
  - auto: []
    identifier: relearn-auto
    name: Relearrrn Light/Dark
  - identifier: relearn-light
  - identifier: relearn-dark
  - identifier: relearn-bright
  - auto:
    - zen-light
    - zen-dark
    identifier: zen-auto
    name: Zen Light/Dark
  - identifier: zen-light
  - identifier: zen-dark
  - auto:
    - learn
    - neon
    identifier: retro-auto
    name: Retro Learn/Neon
  - identifier: neon
  - identifier: learn

{
   "params": {
      "themeVariant": [
         {
            "auto": [],
            "identifier": "relearn-auto",
            "name": "Relearn Light/Dark"
         },
         {
            "identifier": "relearn-light"
         },
         {
            "identifier": "relearn-dark"
         },
         {
            "identifier": "relearn-bright"
         },
         {
            "auto": [
               "zen-light",
               "zen-dark"
            ],
            "identifier": "zen-auto",
            "name": "Zen Light/Dark"
         },
         {
            "identifier": "zen-light"
         },
         {
            "identifier": "zen-dark"
         },
         {
            "auto": [
               "learn",
               "neon"
            ],
            "identifier": "retro-auto",
            "name": "Retro Learn/Neon"
         },
         {
            "identifier": "neon"
         },
         {
            "identifier": "learn"
         }
      ]
   }
}

Advanced Topics

Variant-specific Logos

Ye can override th' default logo o' a ship fer each variant.

Link'n t' a Variant

Ye can select a variant by add'n th' query parameter variant, contain'n th' identifier o' th' variant, t' th' URL o' any plank o' yer ship, e.g. https://example.com/my-page?variant=relearn-dark. This also works fer links 'n yer rrrambl'n.

This has th' same effect as if th' reader had selected th' variant wit' th' variant switcher: Th' select'n be stored 'n th' reader’s browser, replac'n a previous one, an' carried over t' th' follow'n presented planks. Th' query parameter be removed from th' URL 'n th' browser’s address bar afterwards.

Th' variant must be one o' yer configured variants an' must not be hidden. Otherwise th' query parameter be ignored.

Modify'n Variants

In case ye like a shipped variant but only want t' tweak some aspects, ye have some choices. Don’t edit th' file 'n th' theme’s directory! Ye will lose th' ability t' later easily upgrade yer theme t' a newer version.

1. Copy an' change

   Ye can copy th' shipped variant file from th' theme’s themes/hugo-theme-relearn/assets/css directory t' th' site’s assets/css directory an' either store it wit' th' same name or give it a new name. Edit th' sett'ns an' save th' new file. Afterwards, ye can use it 'n yer hugo.toml by th' chosen name.

2. Create an' import

   Ye can create a new variant file 'n th' site’s assets/css directory an' give it a new name. Import th' shipped variant, add th' sett'ns ye want t' change an' save th' new file. Afterwards, ye can use it 'n yer hugo.toml by th' chosen name.

   For example, ye want t' use th' relearn-light variant but want t' change th' rules highlight'n schema t' th' one used 'n th' neon variant. For that, create a new assets/css/theme-my-brand'n.css 'n yer site’s directory an' add th' follow'n lines:

   ​

   assets/css/theme-my-brand'n.css

   @import "theme-relearn-light.css";
   
   :root {
     --CODE-theme: neon; /* name o' th' chroma stylesheet file */
     --CODE-BLOCK-color: rgba(226, 228, 229, 1); /* fallback color fer code text */
     --CODE-BLOCK-BG-color: rgba(40, 42, 54, 1); /* fallback color fer code background */
   }

   Afterwards, put this 'n yer hugo.toml t' use yer new variant:

   hugo.

   toml yaml json

   [params]
     themeVariant = 'my-branding'

   params:
     themeVariant: my-brand'n

   {
      "params": {
         "themeVariant": "my-branding"
      }
   }

   In comparison t' copy an' change, this has th' advantage that ye profit from any adjustments t' th' relearn-light variant while keep'n yer modificat'ns.

Non-standard Modificat'ns

Ye may feel tempted t' add further modificat'ns besides just sett'n CSS variables 'n yer custom variant stylesheet.

While this be poss'ble, please note that due t' th' way th' theme uses th' variant files, th' follow'n will not work

• @font-face rules - they need t' be moved t' assets/css/fonts.css, assets/css/custom.css or layouts/partials/custom-header.html
• rules select'n th' html element - replace html wit' :root

React t' Variant Switches 'n JavaScript

Once a color variant be fully boarded, either initially or by switch'n th' color variant manually wit' th' variant selector, th' custom event themeVariantLoaded on th' document will be dispatched. Ye can add an event listener an' react t' changes.

document.addEventListener( 'themeVariantLoaded', funct'n( e ){
  console.log( e.detail.variant ); // `relearn-light`
});