Colors

The Relearn theme offers color variants to change your site’s appearance. Each color variant contains of a CSS file and optional settings in your hugo.toml.

You can use the shipped variants, customize them, or create your own. The interactive variant generator can help you with this.

Once set up in hugo.toml, you can switch variants using the selector at the bottom of the menu.

Shipped Variants

The theme ships with the following set of variants

• Relearn
  • Light: the classic Relearn default, coming with signature green, dark sidebar and light content area
  • Dark: dark variant of Light, coming with signature green, dark sidebar and dark content area
• Zen
  • Light: a more relaxed white/grey variant, coming with blue accents, light sidebar and light content area
  • Dark: dark variant of Light, coming with blue accents, dark sidebar and dark content area
• Contrast
  • Light: colors chosen for high contrast, coming with black text on white, darker boxes and a matching syntax highlighting
  • Dark: dark variant of Light, coming with white text on black, brighter boxes and a matching syntax highlighting
• Tome
  • Light: a book-like variant, coming with burgundy accents, calligraphic titles, warm paper tones and a glow around the page
  • Dark: dark variant of Light, coming with garnet accents, calligraphic titles, dark leather tones and a glow around the page
• Experimental
  • Neon: a variant that glows in the dark, gradient sidebar and dark content area
• Retro
  • Learn: the default of the old Learn theme, coming with signature light purple, dark sidebar and light content area
  • Blue: a blue variant of the old Learn theme, coming tinted in blue, dark sidebar and light content area
  • Green: a green variant of the old Learn theme, coming tinted in green, dark sidebar and light content area
  • Red: a red variant of the old Learn theme, coming tinted in red, dark sidebar and light content area

Changing the Variant

Option Set the themeVariant option to change the variant.

The theme offers the recommended advanced configuration mode that combines the functionality for multiple variants, OS setting adjustments, and more.

Simple Setup

Single Variant

Set themeVariant to your theme CSS file name:

[params]
  themeVariant = 'relearn-light'

params:
  themeVariant: relearn-light

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

Place your theme file in assets/css or themes/hugo-theme-relearn/assets/css. Name it theme-*.css.

In the above example, the path of your theme file must be assets/css/theme-relearn-light.css or themes/hugo-theme-relearn/assets/css/theme-relearn-light.css.

Multiple Variants

To let the reader choose between multiple variants by displaying 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"
      ]
   }
}

The first variant is the default, and a selector will appear if there’s more than one.

If you want to have more control, where the variant switcher is positioned or you want to configure a different icon, see the chapter on sidebar configuration.

Adjust to OS Settings

Use the auto value to match OS light/dark settings. Usually it makes sense to set it in the first position and make it the default.

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

params:
  themeVariant:
  - auto
  - red

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

If you don’t configure anything else, the theme will default to use relearn-light for light mode and relearn-dark for dark mode.

Default is relearn-light for light and relearn-dark for dark mode. These defaults are overwritten by the first two non-auto options of your themeVariant array.

You can override the default with themeVariantAuto:

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

params:
  themeVariantAuto:
  - learn
  - neon

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

Advanced

The theme offers an advanced way to configure theme variants and all of the aspects above inside of a single configuration item. This comes with some features previously unsupported.

Like with the multiple variants option, you are defining your theme variants in an array but now in a table with suboptions.

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 variant.

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

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

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

you 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"
         }
      ]
   }
}

The identifier option is mandatory and equivalent to the string in the first example. Further options can be configured, see the table below.

Parameters

Variant Parameters

Some of the site’s params can be given a different value for a variant by setting it in the variant’s params. While the variant is active, it takes the place of the site’s value.

[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

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

Dividers

To group the entries of the variant switcher, put an entry { type = 'divider' } between them. It draws a line in the variant switcher and is no variant itself.

Give the divider a name to label the group following it, like { type = 'divider', name = 'Classic' }. A named divider may also stand first to label the first group.

Of consecutive dividers only the last one is kept. Trailing dividers are dropped, as are leading ones without a name.

Example Configuration

[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

{
   "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 page is printed or shown as its print version, it doesn’t use the variant selected by the reader but its print variant, with the theme’s print variables on top.

The print variables set every color that depends on a light or dark background to values made for paper, with links, titles, code, boxes and the topbar in black on white. So the print shows the fonts of the print variant but the colors of paper. The print variables are in the theme’s assets/css/format-print-variables.css. To change them for your site, copy the file into your site’s assets/css directory and edit it. To keep a single value of a print variant on paper, mark it !important in the variant.

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

Option Set themeVariantPrint to the print variant of your site. Default is relearn-light.

[params]
  themeVariantPrint = 'zen-light'

params:
  themeVariantPrint: zen-light

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

With the advanced configuration, each variant can name its own print variant with the print parameter, which wins over themeVariantPrint. A variant naming itself prints with its own fonts.

If a print variant has a different print variant itself, by its print parameter or by themeVariantPrint, that one is used instead, and so on, until a variant names itself. If this comes back to a variant already visited, the build stops with an error. An auto mode variant prints with the print variants of its light and dark variant, following the reader’s OS setting.

In the following example, both variants print with the fonts of the light variant.

[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

{
   "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 to be part of themeVariant. If you list it, set it hidden to keep it out of the variant switcher.

The style rules of a print variant apply to the print as well. If your variant contains style rules that are meant for the screen only, wrap them as follows. The print version of a page is shown on screen too, so @media screen alone is 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 for the screen */
    }
  }
}

Advanced Topics

Variant-specific Logos

You can override the default logo of a site for each variant.

Linking to a Variant

You can select a variant by adding the query parameter variant, containing the identifier of the variant, to the URL of any page of your site, e.g. https://example.com/my-page?variant=relearn-dark. This also works for links in your content.

This has the same effect as if the reader had selected the variant with the variant switcher: The selection is stored in the reader’s browser, replacing a previous one, and carried over to the following presented pages. The query parameter is removed from the URL in the browser’s address bar afterwards.

The variant must be one of your configured variants and must not be hidden. Otherwise the query parameter is ignored.

Modifying Variants

In case you like a shipped variant but only want to tweak some aspects, you have some choices. Don’t edit the file in the theme’s directory! You will lose the ability to later easily upgrade your theme to a newer version.

1. Copy and change

   You can copy the shipped variant file from the theme’s themes/hugo-theme-relearn/assets/css directory to the site’s assets/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 hugo.toml by the chosen name.

2. Create and import

   You can create a new variant file in the site’s assets/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 hugo.toml by the chosen name.

   For example, you want to use the relearn-light variant but want to change the syntax highlighting schema to the one used in the neon variant. For that, create a new assets/css/theme-my-branding.css in your site’s directory and add the following lines:

   ​

   assets/css/theme-my-branding.css

   @import "theme-relearn-light.css";
   
   :root {
     --CODE-theme: neon; /* name of the chroma stylesheet 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 hugo.toml to use your new variant:

   hugo.

   toml yaml json

   [params]
     themeVariant = 'my-branding'

   params:
     themeVariant: my-branding

   {
      "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 while keeping your modifications.

Non-standard Modifications

You may feel tempted to add further modifications besides just setting CSS variables in your custom variant stylesheet.

While this is possible, please note that due to the way the theme uses the variant files, the following will not work

• @font-face rules - they need to be moved to assets/css/fonts.css, assets/css/custom.css or layouts/partials/custom-header.html
• rules selecting the html element - replace html with :root

React to Variant Switches in JavaScript

Once a color variant is fully loaded, either initially or by switching the color variant manually with the variant selector, the custom event themeVariantLoaded on the document will be dispatched. You can add an event listener and react to changes.

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