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 project configurat'n:

   hugo.

   yaml toml json

   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]
     [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": {
            "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.yaml

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 project configurat'n:

   hugo.

   yaml toml json

   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]
     [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",
            "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.yaml

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 t' 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 project configuration) 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 project configurat'n 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.

   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: 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]
     [[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 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 t' 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 project configurat'n

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

   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: 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]
     [[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 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:
  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]
  [[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 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 project configurat'n.

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 project configurat'n
• 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.

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

Ship Title

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

title: Cap'n Hugo Relearrrn Theme

title = '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

params:
  images:
  - images/hero.png

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

{
   "params": {
      "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 yer project configurat'n:

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 set t' true 'n yer project configurat'n. 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 project configurat'n t' someth'n other than th' default o':

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

[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,
         "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 yer project configurat'n:

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 yer project configurat'n:

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 set t' true 'n yer project configurat'n. 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 project configurat'n t' someth'n other than th' default o':

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

[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,
         "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.

An SVG favicon can also adapt itself, so a single favicon.svg be enough. Draw everyth'n that should adapt wit' currentColor an' switch color wit' a prefers-color-scheme media query. This covers fills an' strokes o' all shapes alike, while parts wit' a color o' 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>

Th' svg:root selector restricts th' rules t' th' SVG be'n displayed as an image o' its own. If th' same file be inlined into th' plank, fer example as a logo wit' th' inlinecontent image effect, th' rules do not leak into th' page’s other SVGs an' th' theme colors th' currentColor parts instead.

Some browsers only pick up a changed OS sett'n fer th' favicon after a reload.

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 project configurat'n 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: |-
    Relearrrn
    be th' greatest
    theme since
    sliced bread

[params]
  linkTitle = "Relearn\nis th' greatest\ntheme since\nsliced 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;
    --LOGO-font-weight: 500;
}
</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:
  logo:
    layout: sidebar-column

[params]
  [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

When a plank be printed or shown as its print version, logo an' title be formatted automatically.

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 th' params o' yer project configurat'n. This will override automatic detect'n:

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

[params]
  [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:
  logo:
    src: ' '

[params]
  [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, set logo 'n th' params o' th' variant within yer themeVariant configurat'n:

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

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 src o' th' variant’s params.logo t' a whitespace str'n:

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

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:
  logo:
    src: /images/logo.svg?inlinecontent

[params]
  [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 project configurat'n.

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 yer project configurat'n, 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
• 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
• Tome
  • Light: a book-like variant, com'n wit' burgundy accents, calligraphic titles, warm paper tones an' a glow around th' plank
  • Dark: dark variant o' Light, com'n wit' garnet accents, calligraphic titles, dark leather tones an' a glow around th' plank
• 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 variant.

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

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

Variant Parameters

Some o' th' site’s params can be given a different value fer a variant by sett'n it 'n th' variant’s params. While th' variant be active, it takes th' place o' th' 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

T' group th' entries o' th' variant switcher, put an entry { type = 'divider' } between them. It draws a line 'n th' variant switcher an' be no variant itself.

Give th' divider a name t' label th' group follow'n it, like { type = 'divider', name = 'Classic' }. A named divider may also stand first t' label th' first group.

O' consecutive dividers only th' last one be kept. Trail'n dividers be dropped, as be lead'n ones without a name.

Example Configurat'n

params:
  themeVariant:
  - name: Modern
    type: divider
  - auto: []
    identifier: relearn-auto
    name: Relearrrn 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 plank be printed or shown as its print version, it doesn’t use th' variant selected by th' reader but its print variant, wit' th' theme’s print variables on top.

Th' print variables set every color that depends on a light or dark background t' values made fer paper, wit' links, titles, code, boxes an' th' topbar 'n black on white. So th' print shows th' fonts o' th' print variant but th' colors o' paper. Th' print variables be 'n th' theme’s assets/css/format-print-variables.css. T' change them fer yer ship, copy th' file into yer site’s assets/css directory an' edit it. T' keep a single value o' a print variant on paper, mark it !important 'n th' variant.

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

Opt'n Set themeVariantPrint t' th' print variant o' yer ship. Default be relearn-light.

params:
  themeVariantPrint: zen-light

[params]
  themeVariantPrint = 'zen-light'

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

Wit' th' advanced configurat'n, each variant can name its own print variant wit' th' print parameter, which wins over themeVariantPrint. A variant nam'n itself prints wit' its own fonts.

If a print variant has a different print variant itself, by its print parameter or by themeVariantPrint, that one be used instead, an' so on, until a variant names itself. If this comes back t' a variant already visited, th' build stops wit' an error. An auto mode variant prints wit' th' print variants o' its light an' dark variant, follow'n th' reader’s OS sett'n.

In th' follow'n example, both variants print wit' th' fonts o' th' 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 t' be part o' themeVariant. If ye list it, set it hidden t' keep it out o' th' variant switcher.

Th' style rules o' a print variant apply t' th' print as well. If yer variant contains style rules that be meant fer th' screen only, wrap them as follows. Th' print version o' a plank be shown on screen too, so @media screen alone be 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 fer th' screen */
    }
  }
}

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 project configurat'n 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 project configurat'n 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 project configurat'n t' use yer new variant:

   hugo.

   yaml toml json

   params:
     themeVariant: my-brand'n

   [params]
     themeVariant = 'my-branding'

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