Directory Structure

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

content
- log
  - first-day
    - _index.md
  - second-day
    - index.md
  - third-day.md
  - _index.md
- _index.md
themes
- hugo-theme-relearn
  - …
hugo.toml

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.

Warning

Don’t edit files inside the themes/hugo-theme-relearn directory. That’s not the recommended way to customize! Refer to the explanation above.

Don’t clone the theme repository and edit files there for your site. That’s not the recommended way to customize! Instead, follow the Getting Started guide.

Multilingual

The Relearn theme works with Hugo’s multilingual mode.

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

Supported languages

Arabic
Simplified Chinese
Traditional Chinese
Czech
Danish
Dutch
English
Finnish
French
German
Hindi
Hungarian
Indonesian
Italian
Japanese
Korean
Persian
Polish
Portuguese
Brazilian Portuguese
Romanian
Russian
Spanish
Swahili
Turkish
Ukrainian
Vietnamese

Translation by File Name

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

Set up languages in your hugo.toml file:

hugo.

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

{
   "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
      }
   }
}

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

Translation by Content Directory

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

Set up languages in your hugo.toml file:

hugo.

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

{
   "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
      }
   }
}

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

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=true

hugo.

[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 hugo.toml) 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:

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

Prepare your hugo.toml 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.

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

{
   "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": {}
   }
}

Generate your site and deploy the resulting directory to baseURL as before
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=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.

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

Add the new version to your hugo.toml

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.

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

{
   "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": {}
   }
}

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:

hugo.

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

{
   "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.

content/publishing/gdpr/_index.md

+++
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 hugo.toml.

hugo.

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

hugo.

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

[params]

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

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

Site Title

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

hugo.

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.

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

hugo.

images = ['images/hero.png']

images:
- images/hero.png

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

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 hugo.toml:

hugo.

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

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=true in hugo.toml. 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 hugo.toml to something other than the default of:

hugo.

[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

{
   "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 hugo.toml:

hugo.

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

hugo.

[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=true in hugo.toml. 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 hugo.toml to something other than the default of:

hugo.

[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

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

Site Management