Directory Structure

If you’ve followed the Getting Started guide, your directory layout will look similar to this:

Hugo uses a union file system, which lets you combine multiple directories.

By default, it puts your root directory on top of the Relearn theme directory. Files in your root directory will replace theme files in the same location.

For example, if you create a file at layouts/partials/heading.html, it will override the theme’s themes/hugo-theme-relearn/layouts/partials/heading.html.

See this list, to learn which files are allowed to be overridden by you.

This makes it easy to customize the theme without changing files in the themes directory, making future theme updates simpler.

Multilingual

The Relearn theme works with Hugo’s multilingual mode.

It supports many languages, including right-to-left languages.

Translation by File Name

Here’s how to make your site multilingual using translations by file name:

1. Set up languages in your project configuration:

   hugo.

   yaml toml json

   defaultContentLanguage: en
   languages:
     en:
       label: English
       locale: en
       title: My Website
       weight: 1
     pir:
       direction: rtl
       label: Pirrratish
       locale: art-x-pir
       title: Arrr, my Website
       weight: 2

   defaultContentLanguage = 'en'
   
   [languages]
     [languages.en]
       label = 'English'
       locale = 'en'
       title = 'My Website'
       weight = 1
   
     [languages.pir]
       direction = 'rtl'
       label = 'Pirrratish'
       locale = 'art-x-pir'
       title = 'Arrr, my Website'
       weight = 2

   {
      "defaultContentLanguage": "en",
      "languages": {
         "en": {
            "label": "English",
            "locale": "en",
            "title": "My Website",
            "weight": 1
         },
         "pir": {
            "direction": "rtl",
            "label": "Pirrratish",
            "locale": "art-x-pir",
            "title": "Arrr, my Website",
            "weight": 2
         }
      }
   }

2. Duplicate your content files and add language codes to their file names:

   • content
     • log
       • first-day
         • _index.en.md
         • _index.pir.md
       • second-day
         • index.en.md
         • index.pir.md
       • third-day.en.md
       • third-day.pir.md
       • _index.en.md
       • _index.pir.md
     • _index.en.md
     • _index.pir.md
   • themes
     • hugo-theme-relearn
       • …
   • hugo.yaml

Translation by Content Directory

The theme also support translations by content directory which can be configured in a similar way.

1. Set up languages in your project configuration:

   hugo.

   yaml toml json

   defaultContentLanguage: en
   languages:
     en:
       contentDir: content/en
       label: English
       locale: en
       title: My Website
       weight: 1
     pir:
       contentDir: content/pir
       direction: rtl
       label: Pirrratish
       locale: art-x-pir
       title: Arrr, my Website
       weight: 2

   defaultContentLanguage = 'en'
   
   [languages]
     [languages.en]
       contentDir = 'content/en'
       label = 'English'
       locale = 'en'
       title = 'My Website'
       weight = 1
   
     [languages.pir]
       contentDir = 'content/pir'
       direction = 'rtl'
       label = 'Pirrratish'
       locale = 'art-x-pir'
       title = 'Arrr, my Website'
       weight = 2

   {
      "defaultContentLanguage": "en",
      "languages": {
         "en": {
            "contentDir": "content/en",
            "label": "English",
            "locale": "en",
            "title": "My Website",
            "weight": 1
         },
         "pir": {
            "contentDir": "content/pir",
            "direction": "rtl",
            "label": "Pirrratish",
            "locale": "art-x-pir",
            "title": "Arrr, my Website",
            "weight": 2
         }
      }
   }

2. Duplicate your content files into separate directories named by their language code:

   • content
     • en
       • log
         • first-day
           • _index.md
         • second-day
           • index.md
         • third-day.md
         • _index.md
       • _index.md
     • pir
       • log
         • first-day
           • _index.md
         • second-day
           • index.md
         • third-day.md
         • _index.md
       • _index.md
   • themes
     • hugo-theme-relearn
       • …
   • hugo.yaml

Search Settings

Check the search configuration for multilingual options.

Turn Off Language Switching

Option By default the theme shows a language switcher in the lower part of the menu.

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

To disable the language switcher set disableLanguageSwitchingButton to true

params:
  disableLanguageSwitchingButton: true

[params]
  disableLanguageSwitchingButton = true

{
   "params": {
      "disableLanguageSwitchingButton": true
   }
}

Versioning

The theme supports Hugo’s versions of your site. This is useful if you want to keep older versions of your site available while also providing links to the current version. All versions are generated together in one build of your project.

A version switcher will be displayed at the top of the sidebar if more than one version is configured. If the user selects a different version, the theme will navigate to the same page in the selected version. If this page does not exist in the selected version, the home page of that version will be displayed.

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

Example: Versioning an Existing Nonversioned Site

Assume, you have written a documentation for an app. At some point you are a releasing a new major version. This new version requires enhanced documentation while the older documentation must still be available for users of the older app version.

Your content resides in the directory content of your project. The current URL of your site (the value set in baseURL in your project configuration) is https://example.com/. When done, the URL of the latest version of your site should not change. The archived version of your site should be available at the URL https://example.com/v1.0.0/.

To setup versioning, you have to do the following steps:

1. Copy the directory content to a new directory content-v1.0.0 for the archived version

2. Prepare your project configuration for versioning.

   • add all available versions
   • add information, which of these versions is the latest by setting defaultContentVersion (here to v2.0.0)
   • mount each content directory to the version it belongs to

   After the modifications the config file looks like:

   hugo.

   yaml toml json

   baseURL: https://example.com/
   defaultContentVersion: v2.0.0
   module:
     mounts:
     - sites:
         matrix:
           versions:
           - v1.0.0
       source: content-v1.0.0
       target: content
     - sites:
         matrix:
           versions:
           - v2.0.0
       source: content
       target: content
   versions:
     v1.0.0: {}
     v2.0.0: {}

   baseURL = 'https://example.com/'
   defaultContentVersion = 'v2.0.0'
   
   [module]
     [[module.mounts]]
       source = 'content-v1.0.0'
       target = 'content'
   
       [module.mounts.sites]
         [module.mounts.sites.matrix]
           versions = ['v1.0.0']
   
     [[module.mounts]]
       source = 'content'
       target = 'content'
   
       [module.mounts.sites]
         [module.mounts.sites.matrix]
           versions = ['v2.0.0']
   
   [versions]
     [versions.'v1.0.0']
     [versions.'v2.0.0']

   {
      "baseURL": "https://example.com/",
      "defaultContentVersion": "v2.0.0",
      "module": {
         "mounts": [
            {
               "sites": {
                  "matrix": {
                     "versions": [
                        "v1.0.0"
                     ]
                  }
               },
               "source": "content-v1.0.0",
               "target": "content"
            },
            {
               "sites": {
                  "matrix": {
                     "versions": [
                        "v2.0.0"
                     ]
                  }
               },
               "source": "content",
               "target": "content"
            }
         ]
      },
      "versions": {
         "v1.0.0": {},
         "v2.0.0": {}
      }
   }

3. Generate your site and deploy the resulting directory to baseURL as before

4. Now you’re ready to edit the content of your current version and proceed with your usual workflow.

A few things to note here:

• the version switcher shows the names of your versions as they are configured
• the default version is generated to the root of your site, all other versions into a subdirectory named like the version; set Hugo’s defaultContentVersionInSubdir to true if you want the default version in a subdirectory, too
• once you define a mount, Hugo no longer applies its default mounts for that component; if your project has further mounts, keep them in the list
• only content, layouts and static files can be mounted for a version; everything else, like your configuration and the theme, is shared by all versions
• the source of a mount is not limited to your project and can also be a directory of a different checkout of your version control system
• for a multilingual site, no further configuration is necessary; each version is generated for each language
• copying the whole content is the easiest way but not necessary; you can also store only what has changed

See Hugo’s documentation for the version configuration and the mount configuration for all available settings.

Example: Add a New Version to a Versioned Site

At some point, your version 2 of the app may be deprecated, too, as you’ve released a new version 3.

1. Copy the directory content to a new directory content-v2.0.0 for the new archived version

2. Add the new version to your project configuration

   • add the new version to the versions
   • change defaultContentVersion to the new version (here to v3.0.0)
   • change the mount of content to the new version and add a mount for the new archived version

   After the modifications the config file looks like:

   hugo.

   yaml toml json

   baseURL: https://example.com/
   defaultContentVersion: v3.0.0
   module:
     mounts:
     - sites:
         matrix:
           versions:
           - v1.0.0
       source: content-v1.0.0
       target: content
     - sites:
         matrix:
           versions:
           - v2.0.0
       source: content-v2.0.0
       target: content
     - sites:
         matrix:
           versions:
           - v3.0.0
       source: content
       target: content
   versions:
     v1.0.0: {}
     v2.0.0: {}
     v3.0.0: {}

   baseURL = 'https://example.com/'
   defaultContentVersion = 'v3.0.0'
   
   [module]
     [[module.mounts]]
       source = 'content-v1.0.0'
       target = 'content'
   
       [module.mounts.sites]
         [module.mounts.sites.matrix]
           versions = ['v1.0.0']
   
     [[module.mounts]]
       source = 'content-v2.0.0'
       target = 'content'
   
       [module.mounts.sites]
         [module.mounts.sites.matrix]
           versions = ['v2.0.0']
   
     [[module.mounts]]
       source = 'content'
       target = 'content'
   
       [module.mounts.sites]
         [module.mounts.sites.matrix]
           versions = ['v3.0.0']
   
   [versions]
     [versions.'v1.0.0']
     [versions.'v2.0.0']
     [versions.'v3.0.0']

   {
      "baseURL": "https://example.com/",
      "defaultContentVersion": "v3.0.0",
      "module": {
         "mounts": [
            {
               "sites": {
                  "matrix": {
                     "versions": [
                        "v1.0.0"
                     ]
                  }
               },
               "source": "content-v1.0.0",
               "target": "content"
            },
            {
               "sites": {
                  "matrix": {
                     "versions": [
                        "v2.0.0"
                     ]
                  }
               },
               "source": "content-v2.0.0",
               "target": "content"
            },
            {
               "sites": {
                  "matrix": {
                     "versions": [
                        "v3.0.0"
                     ]
                  }
               },
               "source": "content",
               "target": "content"
            }
         ]
      },
      "versions": {
         "v1.0.0": {},
         "v2.0.0": {},
         "v3.0.0": {}
      }
   }

3. Generate your site and deploy the resulting directory to baseURL

Example: Storing Only What Has Changed

Copying the whole content for each archived version is the easiest way to start, but most pages usually don’t differ between two versions. Instead, an archived version can share the content of the current version and store only the pages that are different.

To stay with the first example, the directory content-v1.0.0 then only contains

• the pages that have changed since, in the state they had in version 1
• the pages that were removed since

The configuration is the same, with one further mount at the end that adds the shared content to the archived version. The added lines are highlighted:

baseURL: https://example.com/
defaultContentVersion: v2.0.0
module:
  mounts:
  - sites:
      matrix:
        versions:
        - v1.0.0
    source: content-v1.0.0
    target: content
  - sites:
      matrix:
        versions:
        - v2.0.0
    source: content
    target: content
  - files:
    - '! whats-new-in-v2/**'
    sites:
      matrix:
        versions:
        - v1.0.0
    source: content
    target: content
versions:
  v1.0.0: {}
  v2.0.0: {}

baseURL = 'https://example.com/'
defaultContentVersion = 'v2.0.0'

[module]
  [[module.mounts]]
    source = 'content-v1.0.0'
    target = 'content'

    [module.mounts.sites]
      [module.mounts.sites.matrix]
        versions = ['v1.0.0']

  [[module.mounts]]
    source = 'content'
    target = 'content'

    [module.mounts.sites]
      [module.mounts.sites.matrix]
        versions = ['v2.0.0']

  [[module.mounts]]
    files = ['! whats-new-in-v2/**']
    source = 'content'
    target = 'content'

    [module.mounts.sites]
      [module.mounts.sites.matrix]
        versions = ['v1.0.0']

[versions]
  [versions.'v1.0.0']
  [versions.'v2.0.0']

{
   "baseURL": "https://example.com/",
   "defaultContentVersion": "v2.0.0",
   "module": {
      "mounts": [
         {
            "sites": {
               "matrix": {
                  "versions": [
                     "v1.0.0"
                  ]
               }
            },
            "source": "content-v1.0.0",
            "target": "content"
         },
         {
            "sites": {
               "matrix": {
                  "versions": [
                     "v2.0.0"
                  ]
               }
            },
            "source": "content",
            "target": "content"
         },
         {
            "files": [
               "! whats-new-in-v2/**"
            ],
            "sites": {
               "matrix": {
                  "versions": [
                     "v1.0.0"
                  ]
               }
            },
            "source": "content",
            "target": "content"
         }
      ]
   },
   "versions": {
      "v1.0.0": {},
      "v2.0.0": {}
   }
}

A few things to note here:

• if two mounts of a version contain the same file, the mount listed first is used; this is why the mount of content-v1.0.0 comes before the mounts of content in the examples
• the pages that were added after version 1 would show up in the archived version as well; leave them out with the files option of the shared mount
• a shared page that links to a page not available in the archived version will cause a warning during the build; store a copy of the shared page in content-v1.0.0 and adjust its link
• with each further archived version, an older version can be put together from its own directory, followed by the directories of the newer archived versions, followed by content

Moved Pages

If a page moved between two versions, the version switcher can not find it by its path. Add the former path to the aliases front matter of the page in the newer version, which you may have done anyway to keep old links working.

---
aliases: /sitemanagement/gdpr
---

+++
aliases = '/sitemanagement/gdpr'
+++

{
   "aliases": "/sitemanagement/gdpr"
}

The version switcher then navigates between both pages in either direction. If a page moves again, add the further path and keep the former ones.

A page at the same path always takes precedence over a page found by an alias.

Linking to Other Versions

Your content can link to a page of another version by giving the query parameter version, containing the name of the version, e.g. [some archived page](my-page?version=v1.0.0).

Unlike the version switcher, such a link does not follow aliases. The page has to exist in the given version under the path you link to.

Hiding the Versioning Warning

Option If visitors navigate to an archived version of your site, they will see a versioning warning at the top of each page.

You can disable it be setting the disableVersioningWarning option to true in your project configuration.

params:
  disableVersioningWarning: true

[params]
  disableVersioningWarning = true

{
   "params": {
      "disableVersioningWarning": true
   }
}

Adjusting the Versioning Warning

Method 1

You can adjust the text of the versioning warning by overriding the key Versioning-warning in your i18n files.

The following parameters are available to be included in the text:

• pageVersion - the displayed page’s version
• pageUrl - the URL of the displayed page
• latestVersion - the default version
• latestUrl - the URL of the displayed page in the default version, or of its home page if the page does not exist there

A version has the following fields:

• identifier - the name of the version
• title - the text shown in the version switcher
• baseURL - the URL of the home page of the version

Method 2

You can override layouts/partials/versioning-warning.html. This is called once a version conflict was recognized. So the only thing for you to do is writing the message.

The following parameters are available in this partial:

• page - the current Page
• pageVersion - the displayed page’s version
• pageUrl - the URL of the displayed page
• latestVersion - the default version
• latestUrl - the URL of the displayed page in the default version, or of its home page if the page does not exist there

Migration for Relearn 9

Previously, versions were configured with the theme’s options versions, version and versionIndexURL. Each version was a separate project that had to be generated and deployed on its own, and an archived version asked the latest version for the list of available versions when a page was displayed.

Your configuration is still honored as long as your project has not more than one of Hugo’s versions configured, but your build will give you a deprecation warning. Start to migrate early, as this will be removed with the next major update of the theme.

To migrate

• bring the content of your separate projects into one project and mount it as shown in the example above
• name Hugo’s versions in a way that the subdirectories of your archived versions stay the same, so links from other sites into your archived versions don’t break
• remove versions, version and versionIndexURL from the params of your project configuration
• deploy all versions from the one build and stop deploying your archived versions separately

Meta Information

Site Author Information

Option The theme uses author details in various parts of your site, like RSS feeds and meta tags.

params:
  author:
    email: santa@example.com
    name: Santa Claus

[params]
  [params.author]
    email = 'santa@example.com'
    name = 'Santa Claus'

{
   "params": {
      "author": {
         "email": "santa@example.com",
         "name": "Santa Claus"
      }
   }
}

Site Title

The title will be used in meta information of your HTML.

title: Hugo Relearn Theme

title = 'Hugo Relearn Theme'

{
   "title": "Hugo Relearn Theme"
}

Site Description

Front Matter The theme shows a site description in various places, such as RSS feeds and meta tags. For this, it uses the description field from your home page’s front matter.

Social Media Images

When your page is shared on social media, you can set a site-wide image to display with the link

params:
  images:
  - images/hero.png

[params]
  images = ['images/hero.png']

{
   "params": {
      "images": [
         "images/hero.png"
      ]
   }
}

More Social Media Options

The theme adheres to Hugo’s official documentation for Open Graph and Twitter Cards configuration.

Available Output Formats

The Relearn theme by default comes with templates for HTML and RSS for each page.

In addition you can configure the below formats.

If this is not enough, learn how to create your own output formats.

Print Support

Enable print support to print entire chapters or the whole site. Add the print output format to your home, section, and page in your project configuration:

outputs:
  home:
  - html
  - rss
  - print
  page:
  - html
  - print
  section:
  - html
  - rss
  - print

[outputs]
  home = ['html', 'rss', 'print']
  page = ['html', 'print']
  section = ['html', 'rss', 'print']

{
   "outputs": {
      "home": [
         "html",
         "rss",
         "print"
      ],
      "page": [
         "html",
         "print"
      ],
      "section": [
         "html",
         "rss",
         "print"
      ]
   }
}

If you want to print the lists of your taxonomies and their terms as well, add it to these, too:

outputs:
  taxonomy:
  - html
  - rss
  - print
  term:
  - html
  - rss
  - print

[outputs]
  taxonomy = ['html', 'rss', 'print']
  term = ['html', 'rss', 'print']

{
   "outputs": {
      "taxonomy": [
         "html",
         "rss",
         "print"
      ],
      "term": [
         "html",
         "rss",
         "print"
      ]
   }
}

The results of the dedicated search page can be printed if your home page can.

By default this adds a printer icon in the topbar but can be deactived. Clicking it switches to print preview, showing the page and its visible subpages in a printer-friendly format. Use your browser’s print function to print or save as PDF.

The URL won’t be configured ugly for Hugo’s URL handling, even with uglyURLs set to true in your project configuration. This is because each mime type can only have one suffix.

If you don’t like the URLs, you can reconfigure outputFormats.print in your project configuration to something other than the default of:

outputFormats:
  print:
    baseName: index.print
    isHTML: true
    mediaType: text/html
    name: print
    noUgly: true
    permalinkable: false

[outputFormats]
  [outputFormats.print]
    baseName = 'index.print'
    isHTML = true
    mediaType = 'text/html'
    name = 'print'
    noUgly = true
    permalinkable = false

{
   "outputFormats": {
      "print": {
         "baseName": "index.print",
         "isHTML": true,
         "mediaType": "text/html",
         "name": "print",
         "noUgly": true,
         "permalinkable": false
      }
   }
}

Markdown Support

Enable support to show the Markdown source of a page. Add the markdown output format to your home, section, and page in your project configuration:

outputs:
  home:
  - html
  - rss
  - markdown
  page:
  - html
  - markdown
  section:
  - html
  - rss
  - markdown

[outputs]
  home = ['html', 'rss', 'markdown']
  page = ['html', 'markdown']
  section = ['html', 'rss', 'markdown']

{
   "outputs": {
      "home": [
         "html",
         "rss",
         "markdown"
      ],
      "page": [
         "html",
         "markdown"
      ],
      "section": [
         "html",
         "rss",
         "markdown"
      ]
   }
}

By default this adds a Markdown icon in the topbar but can be deactived. Clicking it switches to the Markdown source including the title of the page.

The markdown output format configuration is provided by Hugo.

Source Support

Enable support to show the source code of a page if it was generated from a file. Add the source output format to your home, section, and page in your project configuration:

outputs:
  home:
  - html
  - rss
  - source
  page:
  - html
  - source
  section:
  - html
  - rss
  - source

[outputs]
  home = ['html', 'rss', 'source']
  page = ['html', 'source']
  section = ['html', 'rss', 'source']

{
   "outputs": {
      "home": [
         "html",
         "rss",
         "source"
      ],
      "page": [
         "html",
         "source"
      ],
      "section": [
         "html",
         "rss",
         "source"
      ]
   }
}

By default this adds a Source icon in the topbar but can be deactived. Clicking it switches to the source code of the page.

The Source output format differs from the Markdown format, as it prints the source code as is including the front matter.

The URL won’t be configured ugly for Hugo’s URL handling, even with uglyURLs set to true in your project configuration. This is because each mime type can only have one suffix.

If you don’t like the URLs, you can reconfigure outputFormats.source in your project configuration to something other than the default of:

outputFormats:
  source:
    baseName: index.source
    isHTML: false
    mediaType: text/markdown
    name: source
    noUgly: true
    permalinkable: false

[outputFormats]
  [outputFormats.source]
    baseName = 'index.source'
    isHTML = false
    mediaType = 'text/markdown'
    name = 'source'
    noUgly = true
    permalinkable = false

{
   "outputFormats": {
      "source": {
         "baseName": "index.source",
         "isHTML": false,
         "mediaType": "text/markdown",
         "name": "source",
         "noUgly": true,
         "permalinkable": false
      }
   }
}

Logo & Title

Changing the Favicon

If your favicon is an SVG, PNG, or ICO, just drop your image in your site’s assets/images/ or static/images/ directory and name it favicon.svg, favicon.png, or favicon.ico respectively.

If you want to adjust your favicon according to your OS settings for light/dark mode, add the image files assets/images/favicon-light.svg and assets/images/favicon-dark.svg to your site’s directory, respectively, corresponding to your file format. In case some of the files are missing, the theme falls back to favicon.svg for each missing file. All supplied favicons must be of the same file format.

An SVG favicon can also adapt itself, so a single favicon.svg is enough. Draw everything that should adapt with currentColor and switch color with a prefers-color-scheme media query. This covers fills and strokes of all shapes alike, while parts with a color of their own keep it:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" fill="currentColor">
  <style>
    svg:root { color: black; }
    @media (prefers-color-scheme: dark) {
      svg:root { color: white; }
    }
  </style>
  <path d="..."/>
  <circle cx="32" cy="32" r="8" fill="none" stroke="currentColor"/>
</svg>

The svg:root selector restricts the rules to the SVG being displayed as an image of its own. If the same file is inlined into the page, for example as a logo with the inlinecontent image effect, the rules do not leak into the page’s other SVGs and the theme colors the currentColor parts instead.

Some browsers only pick up a changed OS setting for the favicon after a reload.

If no favicon file is found, the theme will look up the alternative filename logo in the same location and will repeat the search for the list of supported file types.

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:

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

Changing the Title

Option The site title of your project configuration will be used for the text at the top of the sidebar. If you want to show a different text in the sidebar, you can overwrite it by setting params.linkTitle.

If the title is to long to fit on a single line it is automatically wrapped.

If you want manual control over the line breaks, you can insert newline characters.

If you want no text at all, set it to a string containing only whitespace like " ".

params:
  linkTitle: |-
    Relearn
    is the greatest
    theme since
    sliced bread

[params]
  linkTitle = "Relearn\nis the greatest\ntheme since\nsliced bread"

{
   "params": {
      "linkTitle": "Relearn\nis the greatest\ntheme since\nsliced bread"
   }
}

Changing the Title Font Settings

You can change font settings with the following CSS variables

<style>
:root {
    --LOGO-font: 'Georgia', serif;
    --LOGO-font-size: 2rem;
    --LOGO-font-weight: 500;
}
</style>

On smaller screens the logo font size is automatically reduced to 80% of the configured value for better mobile display. This is not configurable.

Changing the Title Colors

The logo inherits its colors from the menu header by default. You can customize the normal and hover states

<style>
:root {
    --LOGO-LINK-color: #ff6600;
    --LOGO-LINK-HOVER-color: #ff9933;
}
</style>

The --LOGO-LINK-color variable sets the color of the logo link text, while --LOGO-LINK-HOVER-color sets the color when hovering over the logo.

Setting Layout of Title & Logo

You can control how the logo and title are arranged:

params:
  logo:
    layout: sidebar-column

[params]
  [params.logo]
    layout = 'sidebar-column'

{
   "params": {
      "logo": {
         "layout": "sidebar-column"
      }
   }
}

Valid values are:

• sidebar-row (default) - Logo and title side by side at the top of the menu
• sidebar-column - Logo above title at the top of the menu

When a page is printed or shown as its print version, logo and title are formatted automatically.

Changing the Logo

Option The theme displays a logo in the sidebar menu if found. By default, it automatically detects logos in your site’s assets/images/.

Auto-Detection

If you don’t configure a logo explicitly, the theme automatically searches for a logo file in the global /assets directory and all its subdirectories named *logo*.

If no logo is found, only your site title will be shown.

The size of the logo will adapt automatically to an opinionated default. See below on how to resize it.

Manual Configuration

You can explicitly configure a logo in the params of your project configuration. This will override automatic detection:

params:
  logo:
    src: /images/magic.gif

[params]
  [params.logo]
    src = '/images/magic.gif'

{
   "params": {
      "logo": {
         "src": "/images/magic.gif"
      }
   }
}

To disable the logo entirely, set src to a string containing only whitespace:

params:
  logo:
    src: ' '

[params]
  [params.logo]
    src = ' '

{
   "params": {
      "logo": {
         "src": " "
      }
   }
}

Variant-Specific Logos

The theme supports displaying different logos for different color variants. This allows you to have logos that match each theme variant’s color scheme (e.g., light logo for dark themes, dark logo for light themes).

Variant-specific logos take precedence over the global logo.src setting. If a variant doesn’t specify a logo, the global logo setting will be used.

To configure variant-specific logos, set logo in the params of the variant within your themeVariant configuration:

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

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

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

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

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

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

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

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

The theme automatically switches between logos when the user selects a different variant. Logos with the same src are grouped together for performance optimization, reducing the number of images loaded.

To disable the logo for a specific variant while keeping the default logo for others, set src of the variant’s params.logo to a whitespace string:

params:
  themeVariant:
  - identifier: relearn-light
    params:
      logo:
        src: ' '
  - identifier: relearn-dark

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

    [params.themeVariant.params]
      [params.themeVariant.params.logo]
        src = ' '

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

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

Changing the Size of the Logo

The theme provides CSS variables to customize the logo’s size. You can add these to layouts/partials/custom-header.html. The logo image has a default width of 4em. The height is determined by the aspect ratio of the logo.

<style>
:root {
    --LOGO-IMAGE-width: 6rem;
}
</style>

Coloring SVG Logos

If you have a monochrome SVG logo and want to display it in the variants color for the logo text, it is mandatory to give it the inlinecontent image effect. This is not set in the automatic logo detection.

params:
  logo:
    src: /images/logo.svg?inlinecontent

[params]
  [params.logo]
    src = '/images/logo.svg?inlinecontent'

{
   "params": {
      "logo": {
         "src": "/images/logo.svg?inlinecontent"
      }
   }
}

The recoloring applies to all black elements in your SVG. Elements that get their color from their parent are left untouched. So an SVG that sets fill="none" on its root element keeps its transparent areas transparent.

Changing the SVG Logo Colors

A SVG logo inherits its color from the menu title by default. You can customize both the normal and hover states

<style>
:root {
    --LOGO-IMAGE-color: #0066cc;
    --LOGO-IMAGE-HOVER-color: #0088ff;
}
</style>

Custom Title & Logo Partial

For advanced customization beyond configuration options, you can override the logo partial entirely.

Create a new file layouts/partials/logo.html in your site’s directory. Then write any HTML you want. You could use an img HTML tag and reference an image, or you could paste an SVG definition!

Example

Suppose you’ve stored your logo as static/images/logo.png and want full control over the HTML:

<a id="R-logo" href="{{ partial "permalink.gotmpl" (dict "to" .Site.Home) }}">
  <img src="{{"images/logo.png" | relURL}}" alt="brand logo">
</a>

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 project configuration.

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 your project configuration, 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:
  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"
         }
      ]
   }
}

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:
  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

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:
  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]
  [[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 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:
  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 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 project configuration 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 project configuration 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 project configuration to use your new variant:

   hugo.

   yaml toml 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.