Directory Structure

If you’ve followed th' Gett'n Started guide, yer directory layout will look similar t' this:

Cap'n Hugo uses a union file system, which lets ye combine multiple directories.

By default, it puts yer root directory on top o' th' Relearrrn theme directory. Files 'n yer root directory will replace theme files 'n th' same locat'n.

For example, if ye create a file at layouts/partials/head'n.html, it will override th' theme’s themes/hugo-theme-relearn/layouts/partials/head'n.html.

See this list, t' learn which files be allowed t' be overridden by ye.

This makes it easy t' cust'mize th' theme without chang'n files 'n th' themes directory, mak'n future theme updates simpler.

Multilingual

Th' Relearrrn theme works wit' Hugo’s multilingual mode.

It supports many languages, includ'n right-to-left languages.

Translat'n by File Name

Here’s how t' make yer ship multilingual us'n translat'ns by file name:

1. Set up languages 'n yer hugo.toml file:

   hugo.

   toml yaml json

   defaultContentLanguage = 'en'
   
   [languages]
     [languages.en]
       label = 'English'
       locale = 'en'
       title = 'My Website'
       weight = 1
   
     [languages.pir]
       direct'n = '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:
       direct'n: 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 yer rrrambl'n files an' add language codes t' their file names:

   • rrrambl'n
     • 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

Translat'n by Rrrambl'n Directory

Th' theme also support translat'ns by rrrambl'n directory which can be configured 'n a similar way.

1. Set up languages 'n yer hugo.toml file:

   hugo.

   toml yaml json

   defaultContentLanguage = 'en'
   
   [languages]
     [languages.en]
       contentDir = 'content/en'
       label = 'English'
       locale = 'en'
       title = 'My Website'
       weight = 1
   
     [languages.pir]
       contentDir = 'content/pir'
       direct'n = '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
       direct'n: 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 yer rrrambl'n files into separate directories named by their language code:

   • rrrambl'n
     • 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 Sett'ns

Check th' search configurat'n fer multilingual options.

Turn Off Language Switch'n

Opt'n By default th' theme shows a language switcher 'n th' lower part o' th' menu.

If ye want t' have more control, whar' th' language switcher be positioned or ye want t' configure a different ay'con, see th' chapter on sidebar configurat'n.

T' dis'ble th' language switcher set disableLanguageSwitchingButton=true

[params]
  disableLanguageSwitchingButton = true

params:
  disableLanguageSwitchingButton: true

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

Versioning

Th' theme supports Hugo’s versions o' yer ship. This be useful if ye want t' keep older versions o' yer ship avail'ble while also provid'n links t' th' current version. All versions be generated together 'n one build o' yer project.

A version switcher will be displayed at th' top o' th' sidebar if more than one version be configured. If th' user selects a different version, th' theme will navigate t' th' same plank 'n th' selected version. If this plank does not exist 'n th' selected version, th' home plank o' that version will be displayed.

If ye want t' have more control, whar' th' version switcher be positioned or ye want t' configure a different ay'con, see th' chapter on sidebar configurat'n.

Example: Version'n an Exist'n Nonversioned Ship

Assume, ye have written a documentat'n fer an app. At some point ye be a releas'n a new major version. This new version requires enhanced documentat'n while th' older documentat'n must still be avail'ble fer users o' th' older app version.

Yer rrrambl'n resides 'n th' directory rrrambl'n o' yer project. Th' current URL o' yer ship (the value set 'n baseURL 'n yer hugo.toml) be https://example.com/. When done, th' URL o' th' latest version o' yer ship should not change. Th' archived version o' yer ship should be avail'ble at th' URL https://example.com/v1.0.0/.

T' setup version'n, ye have t' do th' follow'n steps:

1. Copy th' directory rrrambl'n t' a new directory content-v1.0.0 fer th' archived version

2. Prepare yer hugo.toml fer version'n.

   • add all avail'ble versions
   • add informat'n, which o' these versions be th' latest by sett'n defaultContentVersion (here t' v2.0.0)
   • mount each rrrambl'n directory t' th' version it belongs t'

   Aft th' modificat'ns th' config file looks like:

   hugo.

   toml yaml json

   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: rrrambl'n
     - sites:
         matrix:
           versions:
           - v2.0.0
       source: rrrambl'n
       target: rrrambl'n
   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": {}
      }
   }

3. Generate yer ship an' deploy th' result'n directory t' baseURL as before

4. Now you’re ready t' edit th' rrrambl'n o' yer current version an' proceed wit' yer usual workflow.

A few th'ns t' note here:

• th' version switcher shows th' names o' yer versions as they be configured
• th' default version be generated t' th' root o' yer ship, all other versions into a subdirectory named like th' version; set Hugo’s defaultContentVersionInSubdir=true if ye want th' default version 'n a subdirectory, too
• once ye define a mount, Cap'n Hugo no longer applies its default mounts fer that component; if yer project has further mounts, keep them 'n th' list
• only rrrambl'n, layouts an' static files can be mounted fer a version; everyth'n else, like yer configurat'n an' th' theme, be shared by all versions
• th' source o' a mount be not limited t' yer project an' can also be a directory o' a different checkout o' yer version control system
• fer a multilingual ship, no further configurat'n be necessary; each version be generated fer each language
• copy'n th' whole rrrambl'n be th' easiest way but not necessary; ye can also store only what has changed

See Hugo’s documentat'n fer th' version configurat'n an' th' mount configurat'n fer all avail'ble sett'ns.

Example: Add a New Version t' a Versioned Ship

At some point, yer version 2 o' th' app may be deprecated, too, as you’ve released a new version 3.

1. Copy th' directory rrrambl'n t' a new directory content-v2.0.0 fer th' new archived version

2. Add th' new version t' yer hugo.toml

   • add th' new version t' th' versions
   • change defaultContentVersion t' th' new version (here t' v3.0.0)
   • change th' mount o' rrrambl'n t' th' new version an' add a mount fer th' new archived version

   Aft th' modificat'ns th' config file looks like:

   hugo.

   toml yaml json

   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: rrrambl'n
     - sites:
         matrix:
           versions:
           - v2.0.0
       source: content-v2.0.0
       target: rrrambl'n
     - sites:
         matrix:
           versions:
           - v3.0.0
       source: rrrambl'n
       target: rrrambl'n
   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": {}
      }
   }

3. Generate yer ship an' deploy th' result'n directory t' baseURL

Example: Stor'n Only What Has Changed

Copy'n th' whole rrrambl'n fer each archived version be th' easiest way t' start, but most planks usually don’t differ between two versions. Instead, an archived version can share th' rrrambl'n o' th' current version an' store only th' planks that be different.

T' stay wit' th' first example, th' directory content-v1.0.0 then only contains

• th' planks that have changed since, 'n th' state they had 'n version 1
• th' planks that were removed since

Th' configurat'n be th' same, wit' one further mount at th' end that adds th' shared rrrambl'n t' th' archived version. Th' added lines be highlighted:

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: rrrambl'n
  - sites:
      matrix:
        versions:
        - v2.0.0
    source: rrrambl'n
    target: rrrambl'n
  - files:
    - '! whats-new-in-v2/**'
    sites:
      matrix:
        versions:
        - v1.0.0
    source: rrrambl'n
    target: rrrambl'n
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 th'ns t' note here:

• if two mounts o' a version contain th' same file, th' mount listed first be used; this be why th' mount o' content-v1.0.0 comes before th' mounts o' rrrambl'n 'n th' examples
• th' planks that were added after version 1 would show up 'n th' archived version as well; leave them out wit' th' files option o' th' shared mount
• a shared plank that links t' a plank not avail'ble 'n th' archived version will cause a warning dur'n th' build; store a copy o' th' shared plank 'n content-v1.0.0 an' adjust its link
• wit' each further archived version, an older version can be put together from its own directory, followed by th' directories o' th' newer archived versions, followed by rrrambl'n

Moved Planks

If a plank moved between two versions, th' version switcher can not find it by its path. Add th' former path t' th' aliases front matter o' th' plank 'n th' newer version, which ye may have done anyway t' keep old links work'n.

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

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

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

Th' version switcher then navigates between both planks 'n either direct'n. If a plank moves again, add th' further path an' keep th' former ones.

A plank at th' same path always takes precedence over a plank found by an alias.

Link'n t' Other Versions

Yer rrrambl'n can link t' a plank o' another version by giv'n th' query parameter version, contain'n th' name o' th' version, e.g. [some archived page](my-page?version=v1.0.0).

Unlike th' version switcher, such a link does not follow aliases. Th' plank has t' exist 'n th' given version under th' path ye link t'.

Hid'n th' Version'n Arrr

Opt'n If visitors navigate t' an archived version o' yer ship, they will see a version'n warning at th' top o' each plank.

Ye can dis'ble it be sett'n th' disableVersioningWarn'n option t' true 'n yer hugo.toml.

[params]
  disableVersioningWarn'n = true

params:
  disableVersioningWarn'n: true

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

Adjust'n th' Version'n Arrr

Method 1

Ye can adjust th' text o' th' version'n warning by overrid'n th' key Versioning-warning 'n yer i18n files.

Th' follow'n parameters be avail'ble t' be included 'n th' text:

• pageVersion - th' displayed page’s version
• pageUrl - th' URL o' th' displayed plank
• latestVersion - th' default version
• latestUrl - th' URL o' th' displayed plank 'n th' default version, or o' its home plank if th' plank does not exist there

A version has th' follow'n fields:

• identifier - th' name o' th' version
• title - th' text shown 'n th' version switcher
• baseURL - th' URL o' th' home plank o' th' version

Method 2

Ye can override layouts/partials/versioning-warning.html. This be called once a version conflict was recognized. So th' only th'n fer ye t' do be writ'n th' message.

Th' follow'n parameters be avail'ble 'n this partial:

• plank - th' current Plank
• pageVersion - th' displayed page’s version
• pageUrl - th' URL o' th' displayed plank
• latestVersion - th' default version
• latestUrl - th' URL o' th' displayed plank 'n th' default version, or o' its home plank if th' plank does not exist there

Migrat'n fer Relearrrn 9

Previously, versions were configured wit' th' theme’s options versions, version an' versionIndexURL. Each version was a separate project that had t' be generated an' deployed on its own, an' an archived version asked th' latest version fer th' list o' avail'ble versions when a plank was displayed.

Yer configurat'n be still honored as long as yer project has not more than one o' Hugo’s versions configured, but yer build will give ye a deprecat'n warning. Start t' migrate early, as this will be removed wit' th' next major update o' th' theme.

T' migrate

• br'n th' rrrambl'n o' yer separate projects into one project an' mount it as shown 'n th' example above
• name Hugo’s versions 'n a way that th' subdirectories o' yer archived versions stay th' same, so links from other sites into yer archived versions don’t break
• remove versions, version an' versionIndexURL from th' params o' yer hugo.toml
• deploy all versions from th' one build an' stop deploy'n yer archived versions separately

Meta Information

Ship Author Informat'n

Opt'n Th' theme uses author details 'n various parts o' yer ship, like RSS feeds an' meta tags.

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

Ship Title

Th' title will be used 'n meta informat'n o' yer HTML.

title = 'Hugo Relearrrn Theme'

title: Cap'n Hugo Relearrrn Theme

{
   "title": "Hugo Relearrrn Theme"
}

Ship Descript'n

Front Matter Th' theme shows a ship descript'n 'n various places, such as RSS feeds an' meta tags. For this, it uses th' descript'n field from yer home page’s front matter.

Social Media Images

When yer plank be shared on social media, ye can set a site-wide image t' display wit' th' link

images = ['images/hero.png']

images:
- images/hero.png

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

More Social Media Opt'ns

Th' theme adheres t' Hugo’s official documentat'n fer Open Graph an' Twitter Cards configurat'n.

Available Output Formats

Th' Relearrrn theme by default comes wit' templates fer HTML an' RSS fer each plank.

In addit'n ye can configure th' below formats.

If this be not enough, learn how t' create yer own output formats.

Print Support

En'ble print support t' print entire chapters or th' whole ship. Add th' print output format t' yer home, section, an' plank 'n hugo.toml:

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

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

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

If ye want t' print th' lists o' yer taxonomies an' their terms as well, add it t' 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"
      ]
   }
}

Th' results o' th' dedicated search plank can be printed if yer home plank can.

By default this adds a printer ay'con 'n th' topbar but can be deactived. Click'n it switches t' print preview, show'n th' plank an' its vis'ble subpages 'n a printer-friendly format. Use yer browser’s print funct'n t' print or save as PDF.

Th' URL won’t be configured ugly fer Hugo’s URL handl'n, even wit' uglyURLs=true 'n hugo.toml. This be because each mime type can only have one suffix.

If ye don’t like th' URLs, ye can reconfigure outputFormats.print 'n yer hugo.toml t' someth'n other than th' default o':

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

outputFormats:
  print:
    baseName: index.print
    isHTML: true
    mediaType: text/html
    name: print
    noUgly: true
    permalink'ble: false

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

Marrrkdown Support

En'ble support t' show th' Marrrkdown source o' a plank. Add th' markdown output format t' yer home, section, an' plank 'n hugo.toml:

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

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

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

By default this adds a Marrrkdown ay'con 'n th' topbar but can be deactived. Click'n it switches t' th' Marrrkdown source includ'n th' title o' th' plank.

Th' markdown output format configurat'n be provided by Cap'n Hugo.

Source Support

En'ble support t' show th' source code o' a plank if it was generated from a file. Add th' source output format t' yer home, section, an' plank 'n hugo.toml:

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

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

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

By default this adds a Source ay'con 'n th' topbar but can be deactived. Click'n it switches t' th' source code o' th' plank.

Th' Source output format differs from th' Marrrkdown format, as it prints th' source code as be includ'n th' front matter.

Th' URL won’t be configured ugly fer Hugo’s URL handl'n, even wit' uglyURLs=true 'n hugo.toml. This be because each mime type can only have one suffix.

If ye don’t like th' URLs, ye can reconfigure outputFormats.source 'n yer hugo.toml t' someth'n other than th' default o':

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

outputFormats:
  source:
    baseName: index.source
    isHTML: false
    mediaType: text/markdown
    name: source
    noUgly: true
    permalink'ble: false

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

Logo & Title

Chang'n th' Favicon

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

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

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

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

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

Chang'n th' Title

Opt'n Th' ship title o' yer hugo.toml will be used fer th' text at th' top o' th' sidebar. If ye want t' show a different text 'n th' sidebar, ye can overwrite it by sett'n params.linkTitle.

If th' title be t' long t' fit on a single line it be automatically wrapped.

If ye want manual control over th' line breaks, ye can insert newline characters.

If ye want no text at all, set it t' a str'n contain'n only whitespace like " ".

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

params:
  linkTitle: |-
    Relearrrn
    be th' greatest
    theme since
    sliced bread

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

Chang'n th' Title Font Sett'ns

Ye can change font sett'ns wit' th' follow'n CSS variables

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

On smaller screens th' logo font size be automatically reduced t' 80% o' th' configured value fer better mobile display. This be not configur'ble.

Chang'n th' Title Colors

Th' logo inherits its colors from th' menu header by default. Ye can cust'mize th' normal an' hover states

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

Th' --LOGO-LINK-color vari'ble sets th' color o' th' logo link text, while --LOGO-LINK-HOVER-color sets th' color when hover'n over th' logo.

Sett'n Layout o' Title & Logo

Ye can control how th' logo an' title be arranged:

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

params:
  logo:
    layout: sidebar-column

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

Valid values be:

• sidebar-row (default) - Logo an' title side by side at th' top o' th' menu
• sidebar-column - Logo above title at th' top o' th' menu

Chang'n th' Logo

Opt'n Th' theme displays a logo 'n th' sidebar menu if found. By default, it automatically detects logos 'n yer site’s assets/images/.

Auto-Detect'n

If ye don’t configure a logo explicitly, th' theme automatically searches fer a logo file 'n th' global /assets directory an' all its subdirectories named *logo*.

If no logo be found, only yer ship title will be shown.

Th' size o' th' logo will adapt automatically t' an opinionated default. See below on how t' resize it.

Manual Configurat'n

Ye can explicitly configure a logo 'n yer site’s params.toml. This will override automatic detect'n:

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

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

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

T' dis'ble th' logo entirely, set src t' a str'n contain'n only whitespace:

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

params:
  logo:
    src: ' '

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

Variant-Specific Logos

Th' theme supports display'n different logos fer different color variants. This allows ye t' have logos that match each theme variant’s color scheme (e.g., light logo fer dark themes, dark logo fer light themes).

Variant-specific logos take precedence over th' global logo.src sett'n. If a variant doesn’t specify a logo, th' global logo sett'n will be used.

T' configure variant-specific logos, use th' logo field within yer themeVariant configurat'n:

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

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

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

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

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

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

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

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

Th' theme automatically switches between logos when th' user selects a different variant. Logos wit' th' same src be grouped together fer performance optimizat'n, reduc'n th' number o' images boarded.

T' dis'ble th' logo fer a specific variant while keep'n th' default logo fer others, set th' variant’s src t' a whitespace str'n:

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

    [params.themeVariant.logo]
      src = ' '

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

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

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

Chang'n th' Size o' th' Logo

Th' theme provides CSS variables t' cust'mize th' logo’s size. Ye can add these t' layouts/partials/custom-header.html. Th' logo image has a default width o' 4em. Th' height be determined by th' aspect ratio o' th' logo.

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

Color'n SVG Logos

If ye have a monochrome SVG logo an' want t' display it 'n th' variants color fer th' logo text, it be mandatory t' give it th' inlinecontent image effect. This be not set 'n th' automatic logo detect'n.

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

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

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

Th' recolor'n applies t' all black elements 'n yer SVG. Elements that get their color from their parent be left untouched. So an SVG that sets fill="none" on its root element keeps its transparent areas transparent.

Chang'n th' SVG Logo Colors

A SVG logo inherits its color from th' menu title by default. Ye can cust'mize both th' normal an' hover states

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

Custom Title & Logo Partial

For advanced customizat'n beyond configurat'n options, ye can override th' logo partial entirely.

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

Example

Suppose you’ve stored yer logo as static/images/logo.png an' want full control over th' HTML:

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

Brrrand'n

Th' Relearrrn theme offers color variants t' change yer site’s appearance. Each color variant contains o' a CSS file an' optional sett'ns 'n yer hugo.toml.

Ye can use th' shipped variants, cust'mize them, or create yer own. Th' interactive variant generator can help ye wit' this.

Once set up 'n hugo.toml, ye can switch variants us'n th' selector at th' bottom o' th' menu.

Shipped Variants

Th' theme ships wit' th' follow'n set o' variants

• Relearrrn
  • Light: th' classic Relearrrn default, com'n wit' signature green, dark sidebar an' light rrrambl'n area
  • Dark: dark variant o' Light, com'n wit' signature green, dark sidebar an' dark rrrambl'n area
  • Bright: alternative o' Light, com'n wit' signature green, green sidebar an' light rrrambl'n area
• Zen
  • Light: a more relaxed white/grey variant, com'n wit' blue accents, light sidebar an' light rrrambl'n area
  • Dark: dark variant o' Light, com'n wit' blue accents, dark sidebar an' dark rrrambl'n area
• Contrast
  • Light: colors chosen fer high contrast, com'n wit' black text on white, darker boxes an' a match'n rules highlight'n
  • Dark: dark variant o' Light, com'n wit' white text on black, brighter boxes an' a match'n rules highlight'n
• Experimental
  • Neon: a variant that glows 'n th' dark, gradient sidebar an' dark rrrambl'n area
• Retro
  • Learrrn: th' default o' th' old Learrrn theme, com'n wit' signature light purple, dark sidebar an' light rrrambl'n area
  • Blue: a blue variant o' th' old Learrrn theme, com'n tinted 'n blue, dark sidebar an' light rrrambl'n area
  • Green: a green variant o' th' old Learrrn theme, com'n tinted 'n green, dark sidebar an' light rrrambl'n area
  • Red: a red variant o' th' old Learrrn theme, com'n tinted 'n red, dark sidebar an' light rrrambl'n area

Chang'n th' Variant

Opt'n Set th' themeVariant option t' change th' variant.

Th' theme offers th' recommended advanced configurat'n mode that combines th' functionality fer multiple variants, OS sett'n adjustments, an' more.

Simple Setup

Single Variant

Set themeVariant t' yer theme CSS file name:

[params]
  themeVariant = 'relearn-light'

params:
  themeVariant: relearn-light

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

Place yer theme file 'n assets/css or themes/hugo-theme-relearn/assets/css. Name it theme-*.css.

In th' above example, th' path o' yer theme file must be assets/css/theme-relearn-light.css or themes/hugo-theme-relearn/assets/css/theme-relearn-light.css.

Multiple Variants

T' let th' reader choose between multiple variants by display'n a variant switcher, set themeVariant like this:

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

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

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

Th' first variant be th' default, an' a selector will appear if there’s more than one.

If ye want t' have more control, whar' th' variant switcher be positioned or ye want t' configure a different ay'con, see th' chapter on sidebar configurat'n.

Adjust t' OS Sett'ns

Use th' auto value t' match OS light/dark sett'ns. Usually it makes sense t' set it 'n th' first posit'n an' make it th' default.

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

params:
  themeVariant:
  - auto
  - red

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

If ye don’t configure anyth'n else, th' theme will default t' use relearn-light fer light mode an' relearn-dark fer dark mode.

Default be relearn-light fer light an' relearn-dark fer dark mode. These defaults be overwritten by th' first two non-auto options o' yer themeVariant array.

Ye can override th' default wit' themeVariantAuto:

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

params:
  themeVariantAuto:
  - learn
  - neon

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

Advanced

Th' theme offers an advanced way t' configure theme variants an' all o' th' aspects above inside o' a single configurat'n item. This comes wit' some features previously unsupported.

Like wit' th' multiple variants option, ye be defin'n yer theme variants 'n an array but now 'n a table wit' suboptions.

Again, 'n this case, th' first variant be th' default chosen on first view an' a variant selector will be shown 'n th' menu footer if th' array contains more than one entry.

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

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

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

ye now write it that way:

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

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

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

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

Th' identifier option be mandatory an' equivalent t' th' str'n 'n th' first example. Further options can be configured, see th' table below.

Parameters

Example Configurat'n

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

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

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

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

  [[params.themeVariant]]
    auto = ['zen-light', 'zen-dark']
    identifier = 'zen-auto'
    name = 'Zen Light/Dark'

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

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

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

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

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

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

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

Advanced Topics

Variant-specific Logos

Ye can override th' default logo o' a ship fer each variant.

Link'n t' a Variant

Ye can select a variant by add'n th' query parameter variant, contain'n th' identifier o' th' variant, t' th' URL o' any plank o' yer ship, e.g. https://example.com/my-page?variant=relearn-dark. This also works fer links 'n yer rrrambl'n.

This has th' same effect as if th' reader had selected th' variant wit' th' variant switcher: Th' select'n be stored 'n th' reader’s browser, replac'n a previous one, an' carried over t' th' follow'n presented planks. Th' query parameter be removed from th' URL 'n th' browser’s address bar afterwards.

Th' variant must be one o' yer configured variants an' must not be hidden. Otherwise th' query parameter be ignored.

Modify'n Variants

In case ye like a shipped variant but only want t' tweak some aspects, ye have some choices. Don’t edit th' file 'n th' theme’s directory! Ye will lose th' ability t' later easily upgrade yer theme t' a newer version.

1. Copy an' change

   Ye can copy th' shipped variant file from th' theme’s themes/hugo-theme-relearn/assets/css directory t' th' site’s assets/css directory an' either store it wit' th' same name or give it a new name. Edit th' sett'ns an' save th' new file. Afterwards, ye can use it 'n yer hugo.toml by th' chosen name.

2. Create an' import

   Ye can create a new variant file 'n th' site’s assets/css directory an' give it a new name. Import th' shipped variant, add th' sett'ns ye want t' change an' save th' new file. Afterwards, ye can use it 'n yer hugo.toml by th' chosen name.

   For example, ye want t' use th' relearn-light variant but want t' change th' rules highlight'n schema t' th' one used 'n th' neon variant. For that, create a new assets/css/theme-my-brand'n.css 'n yer site’s directory an' add th' follow'n lines:

   ​

   assets/css/theme-my-brand'n.css

   @import "theme-relearn-light.css";
   
   :root {
     --CODE-theme: neon; /* name o' th' chroma stylesheet file */
     --CODE-BLOCK-color: rgba(226, 228, 229, 1); /* fallback color fer code text */
     --CODE-BLOCK-BG-color: rgba(40, 42, 54, 1); /* fallback color fer code background */
   }

   Afterwards, put this 'n yer hugo.toml t' use yer new variant:

   hugo.

   toml yaml json

   [params]
     themeVariant = 'my-branding'

   params:
     themeVariant: my-brand'n

   {
      "params": {
         "themeVariant": "my-branding"
      }
   }

   In comparison t' copy an' change, this has th' advantage that ye profit from any adjustments t' th' relearn-light variant while keep'n yer modificat'ns.

Non-standard Modificat'ns

Ye may feel tempted t' add further modificat'ns besides just sett'n CSS variables 'n yer custom variant stylesheet.

While this be poss'ble, please note that due t' th' way th' theme uses th' variant files, th' follow'n will not work

• @font-face rules - they need t' be moved t' assets/css/fonts.css, assets/css/custom.css or layouts/partials/custom-header.html
• rules select'n th' html element - replace html wit' :root

React t' Variant Switches 'n JavaScript

Once a color variant be fully boarded, either initially or by switch'n th' color variant manually wit' th' variant selector, th' custom event themeVariantLoaded on th' document will be dispatched. Ye can add an event listener an' react t' changes.

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

Module Theming

Change Rules Highlight'n

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

[marrrkup]
  [marrrkup.highlight]
    noClasses = false

marrrkup:
  highlight:
    noClasses: false

{
   "markup": {
      "highlight": {
         "noClasses": false
      }
   }
}

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

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

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

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

Change 3rd-Party Libraries Them'n

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

• mermaid shortcode
• openapi shortcode

Stylesheet Generrrat'r

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

Width

Th' theme adjusts th' menu width based on browser size.

If ye want t' change th' chosen default width, ye can add CSS variables t' layouts/partials/custom-header.html.

Chang'n Menu Width

Th' menu width changes fer different screen sizes:

Ye can change th' menu width but not th' screen width breakpoints.

T' adjust th' menu width, use these CSS variables. Avast that --MENU-S-width be fer th' mobile menu flyout on small screens.

<style>
:root {
    --MENU-S-width: 14.375rem;
    --MENU-M-width: 14.375rem;
    --MENU-L-width: 18.75rem;
}
</style>

Header & Footer

Title & Logo

See th' title & logo configurat'n on how t' set a title an' a logo.

Home Button Configurat'n

By default, th' theme displays a home button between search form an' navigat'n menu. Th' Home button serves as an alternative t' click'n th' logo.

Opt'n T' hide th' Home button on th' left menu, set disableLandingPageButton=true.

[params]
  disableLandingPageButton = true

params:
  disableLandingPageButton: true

{
   "params": {
      "disableLandingPageButton": true
   }
}

Opt'n T' change its ay'con or text, configure th' landingPageName fer yer defined languages.

[languages]
  [languages.en]
    [languages.en.params]
      landingPageName = '<i class="fa-fw fas fa-home"></i> Home'

  [languages.pir]
    [languages.pir.params]
      landingPageName = '<i class="fa-fw fas fa-home"></i> Arrr! Homme'

languages:
  en:
    params:
      landingPageName: <i class="fa-fw fas fa-home"></i> Home
  pir:
    params:
      landingPageName: <i class="fa-fw fas fa-home"></i> Arrr! Homme

{
   "languages": {
      "en": {
         "params": {
            "landingPageName": "\u003ci class=\"fa-fw fas fa-home\"\u003e\u003c/i\u003e Home"
         }
      },
      "pir": {
         "params": {
            "landingPageName": "\u003ci class=\"fa-fw fas fa-home\"\u003e\u003c/i\u003e Arrr! Homme"
         }
      }
   }
}

If this option isn’t set fer a specific language, it will use these default values

[params]
  landingPageName = '<i class="fa-fw fas fa-home"></i> Home'

params:
  landingPageName: <i class="fa-fw fas fa-home"></i> Home

{
   "params": {
      "landingPageName": "\u003ci class=\"fa-fw fas fa-home\"\u003e\u003c/i\u003e Home"
   }
}

For a free configurat'n o' th' header menus, see configurat'n o' th' sidebar menus.

History

Opt'n Turn on showVisitedLinks=true t' see checkmarks next t' visited planks 'n th' main menu. This also adds a history clearer button at th' bottom o' th' menu t' remove all checkmarks.

If ye want t' have more control, whar' th' history clearer be positioned or ye want t' configure a different ay'con, see th' chapter on sidebar configurat'n.

Avast that checkmarks will disappear if ye rebuild yer ship, as th' plank IDs may change.

[params]
  showVisitedLinks = true

params:
  showVisitedLinks: true

{
   "params": {
      "showVisitedLinks": true
   }
}

Footer

T' change th' menu footer, edit th' layouts/partials/menu-footer.html file. Check out th' Partials section fer more ways t' cust'mize yer ship.

Search

Configure Search

Th' theme offers three levels o' search through th' menu’s search form:

1. In-page search: Highlights search terms on th' current plank
2. Search popup: Opens a popup wit' results from other planks
3. Dedicated search plank: Access'ble by click'n th' magnifier glass or press'n ENTER

Each level requires th' previous one t' be enabled. If no search be configured, th' search form won’t appear.

Opt'n All levels be enabled by default. Dis'ble them 'n hugo.toml: