Subsct'ns o' Brrrand'n

Logo

Change th' Favicon

If yer favicon be an SVG, PNG, or ICO, just drop yer image 'n yer site’s static/images/ directory an' name it favicon.svg, favicon.png, or favicon.ico respectively.

If ye want t' adjust yer favicon accord'n t' yer OS sett'ns fer light/dark mode, add th' image files static/images/favicon-light.svg an' static/images/favicon-dark.svg t' yer site’s directory, respectively, correspond'n t' yer file format. In case some o' th' files be miss'n, th' theme falls back t' favicon.svg fer each miss'n file. All supplied favicons must be o' th' same file format.

If no favicon file be found, th' theme will look up th' alternative filename logo 'n th' same locat'n an' will repeat th' search fer th' list o' supported file types.

If ye need t' change this default behavior, create a new file layouts/partials/favicon.html 'n yer site’s directory an' write someth'n like this:

<link rel="icon" href="/images/favicon.bmp" type="image/bmp">

By default, only yer ship title will be shown at th' top o' th' menu. Ye can configure this, or override th' logo partial.

Create a new file 'n layouts/partials/logo.html o' yer ship. Then write any HTML ye want. Ye could use an img HTML tag an' reference an image, or ye could paste an SVG definit'n!

Th' size o' th' logo will adapt automatically.

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
  • 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 opt'n 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:

hugo.
[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, set themeVariant like this:

hugo.
[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.

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.

hugo.
[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 opt'ns o' yer themeVariant array.

Ye can override th' default wit' themeVariantAuto:

hugo.
[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 opt'n, ye be defin'n yer theme variants 'n an array but now 'n a t'ble wit' subopt'ns.

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.

hugo.
[params]
  themeVariant = ['relearn-light', 'relearn-dark']
params:
  themeVariant:
  - relearn-light
  - relearn-dark
{
   "params": {
      "themeVariant": [
         "relearn-light",
         "relearn-dark"
      ]
   }
}

ye now write it that way:

hugo.
[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 opt'n be mandatory an' equivalent t' th' str'n 'n th' first example. Further opt'ns can be configured, see th' t'ble below.

Parameter

Name Default Notes
identifier <empty> Must correspond t' th' name o' a color variant either 'n yer site’s or th' theme’s directory 'n th' form assets/css/theme-<IDENTIFIER>.css.
name see notes Th' name t' be displayed 'n th' variant selector. If not set, th' identifier be used 'n a human read'ble form.
auto <empty> If set, th' variant be treated as an auto mode variant. It has th' same behavior as th' themeVariantAuto opt'n. Th' first entry 'n th' array be th' color variant fer light mode, th' second fer dark mode. Defin'n auto mode variants wit' th' advanced opt'ns has th' benefit that ye can now have multiple auto mode variants instead o' just one wit' th' simple opt'ns.

Example Configurat'n

hugo.
[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

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:

    @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.
    [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.

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

Module Theming

Change Rules Highlight'n

If ye want t' switch th' rules highlight'n theme together wit' yer color variant, first ye need t' configure yer installat'n accord'n t' Hugo’s documentat'n t' provide a rules highlight'n stylesheet file.

hugo.
[marrrkup]
  [marrrkup.highlight]
    noClasses = false
marrrkup:
  highlight:
    noClasses: false
{
   "markup": {
      "highlight": {
         "noClasses": false
      }
   }
}

Ye can use one o' th' shipped stylesheet files or use Cap'n Hugo t' generate a file fer ye.

hugo gen chromastyles --style=monokai > chroma-mycode.css

Th' file must be written t' assets/css/chroma-<NAME>.css. T' use it wit' yer color variant, ye have t' modify --CODE-theme: <NAME> 'n th' color variant stylesheet file.

@import "theme-relearn-light.css";
:root {
  --CODE-theme: mycode; /* name o' th' chroma stylesheet file */
}

Change 3rd-Party Libraries Them'n

Some o' th' shipped shorrrtcodes be us'n 3rd-party libraries. See th' individual shortcode documentat'n on how t' change their them'n.

Stylesheet Generrrat'r

This interactive tool may help ye t' generate yer own color variant stylesheet.

T' get started, first select a color variant from th' variant selector 'n th' lower left sidebar that fits ye best as a start'n point.

Th' graph be interactive an' reflects th' current colors. Ye can click on any o' th' colored boxes t' adjust th' respective color. Th' graph an' th' plank will update accordingly.

Th' arrowed lines reflect how colors be inherited through different parts o' th' theme if th' descendant isn’t overwritten. If ye want t' delete a color an' let it inherit from its parent, just delete th' value from th' input field.

T' better understand this, select th' neon variant an' modify th' different head'n colors. There, colors fer th' head'ns h2, h3 an' h4 be explicitly set. h5 be not set an' inherits its value from h4. h6 be also not set an' inherits its value from h5.

Once you’ve changed a color, th' variant selector will show a “My custom variant” entry an' yer changes be stored 'n th' browser. Ye can browse t' other planks an' even close th' browser without los'n yer changes.

Once ye be satisfied, ye can download th' new variants file an' copy it into yer site’s assets/css directory.

Opt'n Afterwards, ye have t' adjust th' themeVariant opt'n 'n yer hugo.toml t' yer chosen file name. For example, if yer new variants file be named theme-my-custom-variant.css, ye have t' set themeVariant='my-custom-variant' t' use it.

See th' docs fer further configurat'n opt'ns.

Graph