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 project configurat'n.

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 yer project configurat'n, 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
• 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
• Tome
  • Light: a book-like variant, com'n wit' burgundy accents, calligraphic titles, warm paper tones an' a glow around th' plank
  • Dark: dark variant o' Light, com'n wit' garnet accents, calligraphic titles, dark leather tones an' a glow around th' plank
• 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 variant.

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:
  themeVariant:
  - identifier: relearn-light
  - identifier: relearn-dark

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

  [[params.themeVariant]]
    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

Variant Parameters

Some o' th' site’s params can be given a different value fer a variant by sett'n it 'n th' variant’s params. While th' variant be active, it takes th' place o' th' site’s value.

params:
  themeVariant:
  - identifier: relearn-light
  - identifier: neon
    params:
      logo:
        src: /images/logo-neon.svg

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

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

    [params.themeVariant.params]
      [params.themeVariant.params.logo]
        src = '/images/logo-neon.svg'

{
   "params": {
      "themeVariant": [
         {
            "identifier": "relearn-light"
         },
         {
            "identifier": "neon",
            "params": {
               "logo": {
                  "src": "/images/logo-neon.svg"
               }
            }
         }
      ]
   }
}

Dividers

T' group th' entries o' th' variant switcher, put an entry { type = 'divider' } between them. It draws a line 'n th' variant switcher an' be no variant itself.

Give th' divider a name t' label th' group follow'n it, like { type = 'divider', name = 'Classic' }. A named divider may also stand first t' label th' first group.

O' consecutive dividers only th' last one be kept. Trail'n dividers be dropped, as be lead'n ones without a name.

Example Configurat'n

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

[params]
  [[params.themeVariant]]
    name = 'Modern'
    type = 'divider'

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

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

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

  [[params.themeVariant]]
    type = 'divider'

  [[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]]
    name = 'Classic'
    type = 'divider'

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

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

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

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

Print Variant

When a plank be printed or shown as its print version, it doesn’t use th' variant selected by th' reader but its print variant, wit' th' theme’s print variables on top.

Th' print variables set every color that depends on a light or dark background t' values made fer paper, wit' links, titles, code, boxes an' th' topbar 'n black on white. So th' print shows th' fonts o' th' print variant but th' colors o' paper. Th' print variables be 'n th' theme’s assets/css/format-print-variables.css. T' change them fer yer ship, copy th' file into yer site’s assets/css directory an' edit it. T' keep a single value o' a print variant on paper, mark it !important 'n th' variant.

:root {
  --MAIN-LINK-color: rgba( 0, 0, 255, 1 ) !important; /* blue links also on paper */
}

Opt'n Set themeVariantPrint t' th' print variant o' yer ship. Default be relearn-light.

params:
  themeVariantPrint: zen-light

[params]
  themeVariantPrint = 'zen-light'

{
   "params": {
      "themeVariantPrint": "zen-light"
   }
}

Wit' th' advanced configurat'n, each variant can name its own print variant wit' th' print parameter, which wins over themeVariantPrint. A variant nam'n itself prints wit' its own fonts.

If a print variant has a different print variant itself, by its print parameter or by themeVariantPrint, that one be used instead, an' so on, until a variant names itself. If this comes back t' a variant already visited, th' build stops wit' an error. An auto mode variant prints wit' th' print variants o' its light an' dark variant, follow'n th' reader’s OS sett'n.

In th' follow'n example, both variants print wit' th' fonts o' th' light variant.

params:
  themeVariant:
  - auto:
    - my-light
    - my-dark
    identifier: my-auto
  - identifier: my-light
    print: my-light
  - identifier: my-dark
    print: my-light

[params]
  [[params.themeVariant]]
    auto = ['my-light', 'my-dark']
    identifier = 'my-auto'

  [[params.themeVariant]]
    identifier = 'my-light'
    print = 'my-light'

  [[params.themeVariant]]
    identifier = 'my-dark'
    print = 'my-light'

{
   "params": {
      "themeVariant": [
         {
            "auto": [
               "my-light",
               "my-dark"
            ],
            "identifier": "my-auto"
         },
         {
            "identifier": "my-light",
            "print": "my-light"
         },
         {
            "identifier": "my-dark",
            "print": "my-light"
         }
      ]
   }
}

A print variant doesn’t need t' be part o' themeVariant. If ye list it, set it hidden t' keep it out o' th' variant switcher.

Th' style rules o' a print variant apply t' th' print as well. If yer variant contains style rules that be meant fer th' screen only, wrap them as follows. Th' print version o' a plank be shown on screen too, so @media screen alone be not enough.

:root:not([data-r-output-format='print']) {
  @media screen {
    h1 {
      text-shadow: 0 0 4px rgba( 255, 255, 255, 1 ); /* a glow, only fer th' screen */
    }
  }
}

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 project configurat'n 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 project configurat'n 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 project configurat'n t' use yer new variant:

   hugo.

   yaml toml json

   params:
     themeVariant: my-brand'n

   [params]
     themeVariant = 'my-branding'

   {
      "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`
});