Directory Structure

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

├── content
│   ├── first-chapter
│   │   ├── first-page
|   |   |   └── _index.md
│   │   ├── second-page
|   |   |   └── index.md
│   │   └── third-page.md
│   └── _index.md
├── themes
│   └── hugo-theme-relearn
│       └── ...
└── hugo.toml

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

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

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

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

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

Multilingual

The Relearn theme works with Hugo’s multilingual mode.

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

Translation by File Name

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

1. Set up languages in your hugo.toml file:

   hugo.

   toml yaml json

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

   defaultContentLanguage: en
   languages:
     en:
       languageCode: en
       languageName: English
       title: My Website
       weight: 1
     pir:
       languageCode: art-x-pir
       languageDirection: rtl
       languageName: Pirrratish
       title: Arrr, my Website
       weight: 2

   {
      "defaultContentLanguage": "en",
      "languages": {
         "en": {
            "languageCode": "en",
            "languageName": "English",
            "title": "My Website",
            "weight": 1
         },
         "pir": {
            "languageCode": "art-x-pir",
            "languageDirection": "rtl",
            "languageName": "Pirrratish",
            "title": "Arrr, my Website",
            "weight": 2
         }
      }
   }

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

   ├── content
   │   ├── first-chapter
   │   │   ├── first-page
   |   |   |   ├── _index.en.md
   |   |   |   └── _index.pir.md
   │   │   ├── second-page
   |   |   |   ├── index.en.md
   |   |   |   └── index.pir.md
   │   │   ├── third-page.en.md
   │   │   └── third-page.pir.md
   │   ├── _index.en.md
   │   └── _index.pir.md
   ├── themes
   │   └── hugo-theme-relearn
   │       └── ...
   └── hugo.toml

Translation by Content Directory

The theme also support translations by content directory which can be configured in a similar way. This is not used in further examples of this documentation.

Search Settings

Check the search configuration for multilingual options.

Turn Off Language Switching

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

To disable the language switcher set disableLanguageSwitchingButton=true

[params]
  disableLanguageSwitchingButton = true

params:
  disableLanguageSwitchingButton: true

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

Meta Information

Site Author Information

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

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

Site Title

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

title = 'Hugo Relearn Theme'

title: Hugo Relearn Theme

{
   "title": "Hugo Relearn Theme"
}

Site Description

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

Social Media Images

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

images = ['images/hero.png']

images:
- images/hero.png

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

More Social Media Options

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

Deployment Scenarios

Offline Usage

The theme is usable offline. No internet connection is required to load your page. This is achieved by storing all dependencies within the theme.

No calls to 3rd party servers, no calling home, no tracking. Privacy friendly.

Server Deployment

If your server deployment has no special requirements, you can skip this section and use the standard Hugo options.

For special requirements, the theme is capable of different scenarios, requiring the following mandatory settings in your hugo.toml. All settings not mentioned in the examples below can be set to your liking.

Public Web Server from Root

baseURL = 'https://example.com/'

baseURL: https://example.com/

{
   "baseURL": "https://example.com/"
}

Public Web Server from Subdirectory

baseURL = 'https://example.com/mysite/'
relativeURLs = false

baseURL: https://example.com/mysite/
relativeURLs: false

{
   "baseURL": "https://example.com/mysite/",
   "relativeURLs": false
}

If you are still using Hugo’s relref shortcode (which you shouldn’t), you will need further configuration.

Private Web Server (LAN)

The same settings as with any of the public web server scenarios or

baseURL = '/'
relativeURLs = true

baseURL: /
relativeURLs: true

{
   "baseURL": "/",
   "relativeURLs": true
}

File System

Your generated site can be used headless without a HTTP server.

This can be achieved by using the file:// protocol in your browser’s address bar or by double click on a generated *.html file in your file navigation tool.

Use the following settings

baseURL = '/'
relativeURLs = true

baseURL: /
relativeURLs: true

{
   "baseURL": "/",
   "relativeURLs": true
}

Available Output Formats

Print Support

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

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

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

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

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

The URL won’t be configured ugly for Hugo’s URL handling, even with uglyURLs=true in hugo.toml. This is because each mime type can only have one suffix.

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

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

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

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

Stable Output

Disabling the Generator Meta

Option The theme adds a meta tag with its version number to each page.

This isn’t a security risk and helps us support you better.

To turn this off, set disableGeneratorVersion=true.

[params]
  disableGeneratorVersion = true

params:
  disableGeneratorVersion: true

{
   "params": {
      "disableGeneratorVersion": true
   }
}

If you also want to turn off Hugo’s version meta tag, use disableHugoGeneratorInject=true.

Disabling IDs for Referenced Assets

Option The theme creates a unique ID for each build and adds it to each referenced asset’s URL to make browsers not keep outdated cached assets.

This is good for production sites but can be problematic during development. It makes comparing outputs difficult as each build has new IDs.

To disable this, set disableAssetsBusting=true.

[params]
  disableAssetsBusting = true

params:
  disableAssetsBusting: true

{
   "params": {
      "disableAssetsBusting": true
   }
}

Disabling IDs for Interactive HTML Elements

Option Features like expanders, callouts, and tabs use unique IDs to work. These IDs change with each build.

This is necessary for the theme to work properly, but it can make comparing outputs between builds difficult.

To turn this off, set disableRandomIds=true. Note, that this will result in a non-functional site!.

[params]
  disableRandomIds = true

params:
  disableRandomIds: true

{
   "params": {
      "disableRandomIds": true
   }
}

Logo

Change the Favicon

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

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

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

If you need to change this default behavior, create a new file layouts/partials/favicon.html in your site’s directory and write something like this:

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

Change the Logo

By default, only your site title will be shown at the top of the menu. You can configure this, or override the logo partial.

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

The size of the logo will adapt automatically.

Colors

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

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

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

Shipped Variants

The theme ships with the following set of variants

• Relearn
  • Light: the classic Relearn default, coming with signature green, dark sidebar and light content area
  • Dark: dark variant of Light, coming with signature green, dark sidebar and dark content area
  • Bright: alternative of Light, coming with signature green, green sidebar and light content area
• Zen
  • Light: a more relaxed white/grey variant, coming with blue accents, light sidebar and light content area
  • Dark: dark variant of Light, coming with blue accents, dark sidebar and dark content area
• Experimental
  • Neon: a variant that glows in the dark, gradient sidebar and dark content area
• Retro
  • Learn: the default of the old Learn theme, coming with signature light purple, dark sidebar and light content area
  • Blue: a blue variant of the old Learn theme, coming tinted in blue, dark sidebar and light content area
  • Green: a green variant of the old Learn theme, coming tinted in green, dark sidebar and light content area
  • Red: a red variant of the old Learn theme, coming tinted in red, dark sidebar and light content area

Changing the Variant

Option Set the themeVariant option to change the variant.

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

Simple Setup

Single Variant

Set themeVariant to your theme CSS file name:

[params]
  themeVariant = 'relearn-light'

params:
  themeVariant: relearn-light

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

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

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

Multiple Variants

To let the reader choose between multiple variants, set themeVariant like this:

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

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

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

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

Adjust to OS Settings

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

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

params:
  themeVariant:
  - auto
  - red

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

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

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

You can override the default with themeVariantAuto:

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

params:
  themeVariantAuto:
  - learn
  - neon

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

Advanced

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

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

Again, in this case, the first variant is the default chosen on first view and a variant selector will be shown in the menu footer if the array contains more than one entry.

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

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

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

you now write it that way:

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

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

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

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

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

Parameter

Example Configuration

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

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

Modifying Variants

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

1. Copy and change

   You can copy the shipped variant file from the theme’s themes/hugo-theme-relearn/assets/css directory to the site’s assets/css directory and either store it with the same name or give it a new name. Edit the settings and save the new file. Afterwards, you can use it in your hugo.toml by the chosen name.

2. Create and import

   You can create a new variant file in the site’s assets/css directory and give it a new name. Import the shipped variant, add the settings you want to change and save the new file. Afterwards, you can use it in your hugo.toml by the chosen name.

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

   ​

   assets/css/theme-my-branding.css

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

   Afterwards, put this in your hugo.toml to use your new variant:

   hugo.

   toml yaml json

   [params]
     themeVariant = 'my-branding'

   params:
     themeVariant: my-branding

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

   In comparison to copy and change, this has the advantage that you profit from any adjustments to the relearn-light variant while keeping your modifications.

React to Variant Switches in JavaScript

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

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

Module Theming

Change Syntax Highlighting

If you want to switch the syntax highlighting theme together with your color variant, first you need to configure your installation according to Hugo’s documentation to provide a syntax highlighting stylesheet file.

[markup]
  [markup.highlight]
    noClasses = false

markup:
  highlight:
    noClasses: false

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

You can use one of the shipped stylesheet files or use Hugo to generate a file for you.

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

The file must be written to assets/css/chroma-<NAME>.css. To use it with your color variant, you have to modify --CODE-theme: <NAME> in the color variant stylesheet file.

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

Change 3rd-Party Libraries Theming

Some of the shipped shortcodes are using 3rd-party libraries. See the individual shortcode documentation on how to change their theming.

• mermaid shortcode
• openapi shortcode

Stylesheet Generator

This interactive tool may help you to generate your own color variant stylesheet.

Download variant Reset variant

Download variant Reset variant

Width

The theme adjusts the menu width based on browser size.

If you want to change the chosen default width, you can add CSS variables to layouts/partials/custom-header.html.

Changing Menu Width

The menu width changes for different screen sizes:

You can change the menu width but not the screen width breakpoints.

To adjust the menu width, use these CSS variables. Note that --MENU-WIDTH-S is for the mobile menu flyout on small screens.

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

Header & Footer

Title

Option With the default partials for the logo, The site title will also be used for the text at the top of the sidebar. If you want to show a different text in the sidebar, you can overwrite linkTitle.

[params]
  linkTitle = 'Relearn'

params:
  linkTitle: Relearn

{
   "params": {
      "linkTitle": "Relearn"
   }
}

Home Button Configuration

By default, the theme displays a home button between search form and navigation menu. The Home button serves as an alternative to clicking the logo.

Option To hide the Home button on the left menu, set disableLandingPageButton=true.

[params]
  disableLandingPageButton = true

params:
  disableLandingPageButton: true

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

Option To change its icon or text, configure the landingPageName for your 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 for 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"
   }
}

History

Option Turn on showVisitedLinks=true to see checkmarks next to visited pages in the main menu. This also adds a Clear History option at the bottom of the menu to remove all checkmarks. Note that checkmarks will disappear if you rebuild your site, as the page IDs may change.

[params]
  showVisitedLinks = true

params:
  showVisitedLinks: true

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

Footer

To change the menu footer, edit the layouts/partials/menu-footer.html file. Check out the Partials section for more ways to customize your site.

Search

Configure Search

The theme offers three levels of search through the menu’s search form:

1. In-page search: Highlights search terms on the current page
2. Search popup: Opens a popup with results from other pages
3. Dedicated search page: Accessible by clicking the magnifier glass or pressing ENTER

Each level requires the previous one to be enabled. If no search is configured, the search form won’t appear.

Option All levels are enabled by default. Disable them in hugo.toml:

• In-page search: disableSearch=true
• Search popup: disableSearchIndex=true
• Dedicated search page: disableSearchPage=true

[params]
  disableSearch = true
  disableSearchIndex = true
  disableSearchPage = true

params:
  disableSearch: true
  disableSearchIndex: true
  disableSearchPage: true

{
   "params": {
      "disableSearch": true,
      "disableSearchIndex": true,
      "disableSearchPage": true
   }
}

Option Default URLs can be changed with the following parameter

• Search popup: searchindex.js set by searchIndexURL
• Dedicated search page: search/index.html set by searchPageURL

[params]
  searchIndexURL = 'omnisearchindex.js'
  searchPageURL = 'omnisearch'

params:
  searchIndexURL: omnisearchindex.js
  searchPageURL: omnisearch

{
   "params": {
      "searchIndexURL": "omnisearchindex.js",
      "searchPageURL": "omnisearch"
   }
}

Supported Languages

The Lunr search library doesn’t support all languages of the theme. Unsupported languages will show errors in the browser console. Currently unsupported are

• Czech
• Indonesian
• Polish
• Swahili

Mixed Language Support

Option In case your page’s content contains text in multiple languages (for example, you are writing a Piratish documentation for your English API), you can set those languages in additionalContentLanguage to broaden the search.

[params]
  additionalContentLanguage = ['en']

params:
  additionalContentLanguage:
  - en

{
   "params": {
      "additionalContentLanguage": [
         "en"
      ]
   }
}

You can add multiple languages to this array.

Menus

The theme can build menu trees from the structure of your page files or from Hugo’s build in menu feature.

• Option All configuration options in your hugo.toml apply to all menus but can be changed individually.

• Front Matter In case of page structure menus, individual configuration is done via a page’s front matter.

• Menu. In case of Hugo menus, individual configuration is done via a menu entry’s configuration.

Expand State of Submenus

Option Front Matter You can change how submenus appear with alwaysopen.

Menu For Hugo menus, you have to set params.alwaysopen instead.

If alwaysopen=false for any given entry, its children will not be shown in the menu as long as it is not necessary for the sake of navigation.

The theme generates the expand state based on the following rules:

• all parent entries of the active page including their visible siblings are shown regardless of any settings
• immediate child entries of the active entry are shown regardless of any settings
• if not overridden, all other first level entries behave like they would have been given alwaysopen=false
• if not overridden, all other entries of levels besides the first behave like they would have been given alwaysopen=true
• all visible entries show their immediate child entries if alwaysopen=true; this proceeds recursively
• all remaining entries are not shown

alwaysopen = false

alwaysopen: false

{
   "alwaysopen": false
}

Expander for Submenus

Option Front Matter Set collapsibleMenu=true to show submenus as collapsible trees with a clickable expander.

Menu For Hugo menus, you have to set params.collapsibleMenu=true instead.

collapsibleMenu = true

collapsibleMenu: true

{
   "collapsibleMenu": true
}

Ordering Menu Entries

By Weight

Front Matter Menu Hugo provides a simple way to handle order of your entries by setting the weight front matter to a number.

Hugo menus can only be sorted using the weight method.

weight = 5

weight: 5

{
   "weight": 5
}

By Other

Using the weight for sorting can get cumbersome if you, for example, just want to sort alphabetically. Each time you add a new page in the set of pages, you may have to renumber some or all of them to make space for the new page.

Option Front Matter Use ordersectionsby to sort by other aspects. See the children shortcode for a complete list.

ordersectionsby = 'linktitle'

ordersectionsby: linktitle

{
   "ordersectionsby": "linktitle"
}

Title for Menu Entries

Front Matter A page’s linkTitle or title front matter will be used for naming a menu entry of a page menu, in that order if both are defined. Using linkTitle helps to shorten the text for menu entries if the page’s title is too descriptive.

Menu A menu entry’s title or name will be used for naming a menu entry of a Hugo menu, in that order if both are defined.

For example for a page named install/linux.md

+++
linkTitle = 'Linux'
title = 'Install on Linux'
+++

---
linkTitle: Linux
title: Install on Linux
---

{
   "linkTitle": "Linux",
   "title": "Install on Linux"
}

Icons for Menu Entries

Front Matter For page menus, add a menuPre to insert any HTML code before the menu label. You can also set menuPost to insert HTML code after the menu label.

Menu For Hugo menus, add a pre to insert any HTML code before the menu label. You can also set post to insert HTML code after the menu label.

If pageRef is set for the menu entry and no pre or post was configured, menuPre and menuPost of the referenced page will be taken.

The example below uses the GitHub icon for an entry of a page menu.

+++
menuPre = '<i class="fab fa-github"></i> '
title = 'GitHub Repo'
+++

---
menuPre: '<i class="fab fa-github"></i> '
title: GitHub Repo
---

{
   "menuPre": "\u003ci class=\"fab fa-github\"\u003e\u003c/i\u003e ",
   "title": "GitHub Repo"
}

Disable Menu Entries

You may want to structure your entries in a hierarchical way but don’t want to generate clickable parent entries? The theme got you covered.

For Page Menus

To stay with the initial example: Suppose you want first-chapter/first-page appear in the sidebar but don’t want to generate a page for it. So the entry in the sidebar should not be clickable but should be expandable.

For this, open content/first-chapter/first-page/_index.md and add the following front matter

+++
[_build]
  render = 'never'
+++

---
_build:
  render: never
---

{
   "_build": {
      "render": "never"
   }
}

For Hugo Menus

Just don’t give your parent menu entry configuration a url or pageRef. See the next section for a special case.

If you want to learn how to configure different Hugo menus for each language, see the official docs.

+++
[menu]
  [[menu.addendum]]
    name = 'Parent 1'
    weight = 1

  [[menu.addendum]]
    name = 'Child 1'
    parent = 'Parent 1'
    url = 'https://example.com/1'

  [[menu.addendum]]
    name = 'Parent 2'
    weight = 2

  [[menu.addendum]]
    name = 'Child 2'
    parent = 'Parent 2'
    url = 'https://example.com/2'
+++

---
menu:
  addendum:
  - name: Parent 1
    weight: 1
  - name: Child 1
    parent: Parent 1
    url: https://example.com/1
  - name: Parent 2
    weight: 2
  - name: Child 2
    parent: Parent 2
    url: https://example.com/2
---

{
   "menu": {
      "addendum": [
         {
            "name": "Parent 1",
            "weight": 1
         },
         {
            "name": "Child 1",
            "parent": "Parent 1",
            "url": "https://example.com/1"
         },
         {
            "name": "Parent 2",
            "weight": 2
         },
         {
            "name": "Child 2",
            "parent": "Parent 2",
            "url": "https://example.com/2"
         }
      ]
   }
}

Title for Menus

Each menu may have an optional title above its tree. This must be activated for each menu by setting disableMenuTitle=false for each sidebar menu configuration.

Front Matter For page menus, set the menuTitle front matter for the root page of the menu. For example in the home page for the default sidebar menu. If no menuTitle was set, the title will be taken from your translation files by the key <identifier>-menuTitle, where <identifier> is the identifier of your sidebar menu configuration.

Menu For Hugo menus, the title will be taken from your translation files by the key <identifier>-menuTitle, where <identifier> is the identifier of your sidebar menu configuration.

If you don’t want to fiddle around with your translation files, you also have the possibility to let the title be taken from the menu definition. For that, define a nested menu that only has one top-level entry without url or pageRef.

In this case, the title or name is taken for the menu heading.

If you want to learn how to configure different Hugo menus for each language, see the official docs.

+++
[menu]
  [[menu.addendum]]
    name = 'A Menu Title for the Whole Menu'

  [[menu.addendum]]
    name = 'A Menu Entry Title for Child 1'
    parent = 'Parent'
    url = 'https://example.com/1'
    weight = 1

  [[menu.addendum]]
    name = 'A Menu Entry Title for Child 2'
    parent = 'Parent'
    url = 'https://example.com/2'
    weight = 2
+++

---
menu:
  addendum:
  - name: A Menu Title for the Whole Menu
  - name: A Menu Entry Title for Child 1
    parent: Parent
    url: https://example.com/1
    weight: 1
  - name: A Menu Entry Title for Child 2
    parent: Parent
    url: https://example.com/2
    weight: 2
---

{
   "menu": {
      "addendum": [
         {
            "name": "A Menu Title for the Whole Menu"
         },
         {
            "name": "A Menu Entry Title for Child 1",
            "parent": "Parent",
            "url": "https://example.com/1",
            "weight": 1
         },
         {
            "name": "A Menu Entry Title for Child 2",
            "parent": "Parent",
            "url": "https://example.com/2",
            "weight": 2
         }
      ]
   }
}

Title for the Predefined Shortcut Menu

Option By default, the predefined shortcut menu has a the title More (in the English translation).

You can disable this title with disableShortcutsTitle=true.

[params]
  disableShortcutsTitle = true

params:
  disableShortcutsTitle: true

{
   "params": {
      "disableShortcutsTitle": true
   }
}

To change the title, override your translation file.

[shortcuts-menuTitle]
other = "Other Great Stuff"

Defining Sidebar Menus

Option Front Matter Menus are defined using the sidebarmenus option.

You can define as many menus, as you like. If you don’t overwrite this option, the theme defaults to

[[sidebarmenus]]
  disableTitle = true
  identifier = 'home'
  main = true
  pageRef = ''
  type = 'page'

[[sidebarmenus]]
  disableTitle = false
  identifier = 'shortcuts'
  main = false
  type = 'menu'

sidebarmenus:
- disableTitle: true
  identifier: home
  main: true
  pageRef: ""
  type: page
- disableTitle: false
  identifier: shortcuts
  main: false
  type: menu

{
   "sidebarmenus": [
      {
         "disableTitle": true,
         "identifier": "home",
         "main": true,
         "pageRef": "",
         "type": "page"
      },
      {
         "disableTitle": false,
         "identifier": "shortcuts",
         "main": false,
         "type": "menu"
      }
   ]
}

Parameter

Redefining Sidebar Menus for Certain Pages

Suppose you are building a site that contains a topmost blog and documentation section.

When the user is on one of the blog pages he should only see a menu containing all blog pages, while on a documentation page he should only see a menu containing all doc pages.

Directory structure:

content
├── blog
│   ├── post-1.md
│   ├── post-2.md
│   ├── post-3.md
│   └── _index_.md
├── docs
│   ├── topic-1.md
│   ├── topic-2.md
│   ├── topic-3.md
│   └── _index_.md
└── _index.md

Option Front Matter Using Hugo’s cascade feature, we can redefine the menus once in blog/_index.md and docs/_index.md setting sidebarmenus so they will be used in all children pages.

+++
title = 'Blog'

[[cascade]]
  [cascade.params]
    [[cascade.params.sidebarmenus]]
      identifier = 'blog'
      pageRef = '/blog'
      type = 'page'
+++

---
cascade:
- params:
    sidebarmenus:
    - identifier: blog
      pageRef: /blog
      type: page
title: Blog
---

{
   "cascade": [
      {
         "params": {
            "sidebarmenus": [
               {
                  "identifier": "blog",
                  "pageRef": "/blog",
                  "type": "page"
               }
            ]
         }
      }
   ],
   "title": "Blog"
}

+++
title = 'Documentation'

[[cascade]]
  [cascade.params]
    [[cascade.params.sidebarmenus]]
      identifier = 'docs'
      pageRef = '/docs'
      type = 'page'
+++

---
cascade:
- params:
    sidebarmenus:
    - identifier: docs
      pageRef: /docs
      type: page
title: Documentation
---

{
   "cascade": [
      {
         "params": {
            "sidebarmenus": [
               {
                  "identifier": "docs",
                  "pageRef": "/docs",
                  "type": "page"
               }
            ]
         }
      }
   ],
   "title": "Documentation"
}

Displaying Arbitrary Links in a Page Menu

You may have the need to add arbitrary links at some point in your menu that are initially not backed by a page. These are called crosslinks.

Assume the following structure

content
├── reference
│   ├── ref-a.md
│   ├── ref-b.md
│   ├── ref-c.md
│   └── _index_.md
├── topic-blue.md
├── topic-red.md
├── topic-yellow.md
└── _index_.md

You now want to include ref-b as separate entry after topic-green in your menu.

For that create a new page with the following front matter

+++
menuPageRef = '/reference/ref-b'
title = 'Topic Green'
+++

---
menuPageRef: /reference/ref-b
title: Topic Green
---

{
   "menuPageRef": "/reference/ref-b",
   "title": "Topic Green"
}

Front Matter If you want to link to an external page instead, you can use menuUrl instead of menuPageRef.

Pages defining a crosslink are never part of the arrow navigation and are skipped instead.

So with the above example and alphabetical sorting of the menu entries, pressing on topic-blue will skip the newly added topic-green and instead will load topic-red.

Having sub pages below a page that defines a crosslink is undefined.

Displaying Pages Exclusively in a Hugo Menu

Sometimes you want to hide pages from the page menu but instead want to show them in a Hugo menu. For that you have two choices

1. Create a headless branch bundle, _index.md in its own folder with the below front matter. The branch bundle will not be contained in the sitemap.

   content/showcase/_index.en.md

   toml yaml json

   +++
   title = 'Showcase'
   
   [_build]
     list = 'never'
     publishResources = true
     render = 'always'
   +++

   ---
   _build:
     list: never
     publishResources: true
     render: always
   title: Showcase
   ---

   {
      "_build": {
         "list": "never",
         "publishResources": true,
         "render": "always"
      },
      "title": "Showcase"
   }

2. Or, put a child page inside a headless branch bundle with the following front matter in the bundle. This causes the child but not the branch bundle to be contained in the sitemap.

   content/more/_index.en.md

   toml yaml json

   +++
   [_build]
     list = 'never'
     publishResources = false
     render = 'never'
   +++

   ---
   _build:
     list: never
     publishResources: false
     render: never
   ---

   {
      "_build": {
         "list": "never",
         "publishResources": false,
         "render": "never"
      }
   }

   The child page can be any type of content.

   content/more/credits_index.en.md

   toml yaml json

   +++
   title = 'Credits'
   +++

   ---
   title: Credits
   ---

   {
      "title": "Credits"
   }

Width

The theme adjusts the content width when you resize your browser.

If you want to change the chosen default width, you can add CSS variables to layouts/partials/custom-header.html.

Changing the Main Area’s Maximum Width

The main area has a default maximum width of 80.25rem for better readability. If you want to change this, you can set a CSS variable

For full width, use a large value like 1000rem.

<style>
:root {
    --MAIN-WIDTH-MAX: 1000rem;
}
</style>

Titles & Breadcrumbs

Breadcrumbs

Learn how to turn off the breadcrumbs completely and further configure the topbar.

Option Set disableRootBreadcrumb=true to remove the root breadcrumb which often feels redundant. This will also apply to the breadcrumbs of the search results and taxonomy pages.

Option You can override the default breadcrumb separator by using breadcrumbSeparator='/'. This separator will also be used in the breadcrumbs of the search results and taxonomy pages.

Option By default the term pages of a taxonomy will display the breadcrumb for each page. Set disableTermBreadcrumbs=true to remove the breadcrumb if the term pages look to cluttered.

[params]
  breadcrumbSeparator = '/'
  disableRootBreadcrumb = true
  disableTermBreadcrumbs = true

params:
  breadcrumbSeparator: /
  disableRootBreadcrumb: true
  disableTermBreadcrumbs: true

{
   "params": {
      "breadcrumbSeparator": "/",
      "disableRootBreadcrumb": true,
      "disableTermBreadcrumbs": true
   }
}

Titles

Option You can override the default title separator by using titleSeparator='|'.

[params]
  titleSeparator = '|'

params:
  titleSeparator: '|'

{
   "params": {
      "titleSeparator": "|"
   }
}

Headings

Headings can have anchor links that appear when you hover over them.

You can change what happens when you click the anchor icon in your hugo.toml file. By default, all options are turned on. If you turn off all options, no anchor icon will show up when you hover.

Copy Anchor Links

Option Set disableAnchorCopy=true to prevent copying the anchor link when you click the icon.

[params]
  disableAnchorCopy = true

params:
  disableAnchorCopy: true

{
   "params": {
      "disableAnchorCopy": true
   }
}

Scroll to Heading

Option Set disableAnchorScrolling=true to stop the page from scrolling to the heading when you click the anchor icon.

[params]
  disableAnchorScrolling = true

params:
  disableAnchorScrolling: true

{
   "params": {
      "disableAnchorScrolling": true
   }
}

Linking

Further settings are available to be used in your configuration or front matter.

URL Management

Option By default, the theme adds index.html to page links when uglyURLs=false (Hugo’s default).

If you’re only using a web server scenario and dislike this, you can reset to Hugo’s default behavior by settings disableExplicitIndexURLs=true.

For the file system scenario, you are not allowed to change this value.

[params]
  disableExplicitIndexURLs = true

params:
  disableExplicitIndexURLs: true

{
   "params": {
      "disableExplicitIndexURLs": true
   }
}

Patching the relref Shortcode

Option While the usage of relref is obsolete and discouraged by Hugo for a while, existing installations may still use it.

In configurations using a baseURL with a subdirectory and having relativeURLs=false (the default), Hugo’s standard relref implementation is failing.

To work around this, you can activate a patched version of the shortcode by setting disableDefaultRelref=true.

[params]
  disableDefaultRelref = true

params:
  disableDefaultRelref: true

{
   "params": {
      "disableDefaultRelref": true
   }
}

Hidden Pages

This theme allows you to create hidden pages.

Hidden pages are created but not shown in the navigation. This is useful for pages you only want to access via a direct link.

When you visit a hidden page’s URL, it will appear in the navigation menu.

Hidden pages can also have hidden subpages, creating multiple levels of hiding.

By default, hidden pages are only hidden from human visitors. Search engines can still find them by crawling your site and the pages are linked in your taxonomies and site search. You can prevent this with these options.

Hide from Search

Option To remove hidden pages from search results, use disableSearchHiddenPages=true.

[params]
  disableSearchHiddenPages = true

params:
  disableSearchHiddenPages: true

{
   "params": {
      "disableSearchHiddenPages": true
   }
}

Hide from Search Engines

Option To hide pages from search engines by removing them from the sitemap, RSS feed and make them nofollow, use disableSeoHiddenPages=true.

[params]
  disableSeoHiddenPages = true

params:
  disableSeoHiddenPages: true

{
   "params": {
      "disableSeoHiddenPages": true
   }
}

Hide from Taxonomies

Option To prevent hidden pages from appearing on taxonomy and term pages, use disableTagHiddenPages=true. If this makes a term’s count zero, an empty term page will still be created but not linked.

[params]
  disableTagHiddenPages = true

params:
  disableTagHiddenPages: true

{
   "params": {
      "disableTagHiddenPages": true
   }
}

Partials

Usable Partials

You can call other partials from themes/hugo-relearn-themes/ besides those in themes/hugo-relearn-themes/layouts/partials/_relearn. However, using partials not mentioned as customizable below might make future updates more challenging.

Customizable Partials

The Relearn theme allows you to customize various parts of the theme by overriding partials. This makes the theme highly configurable.

A good rule to follow: The less code a partial contains, the easier it will be to update the theme in the future.

Here’s a list of partials you can safely override:

• layouts/partials/content.html: The main content of a page. Override this to display additonal page metadata.

• layouts/partials/content-header.html: The header above the title. By default, it shows tags, but you can change this.

• layouts/partials/content-footer.html: The footer below the content. By default, it shows author info, modification dates, and categories. You can customize this.

• layouts/partials/custom-header.html: For adding custom CSS. Remember to include the style HTML tag.

• layouts/partials/custom-footer.html: For adding custom JavaScript. Remember to include the script HTML tag.

• layouts/partials/favicon.html: The favicon. You should definitely customize this.

• layouts/partials/heading.html: the page’s title headings

• layouts/partials/heading-pre.html: Add content before the page’s title headings. Remember to consider the headingPre front matter.

• layouts/partials/heading-post.html: Add content after the page’s title headings. Remember to consider the headingPost front matter.

• layouts/partials/logo.html: The logo in the top left corner. You should customize this.

• layouts/partials/menu-pre.html: Add content before menu items. Remember to consider the menuPre front matter.

• layouts/partials/menu-post.html: Add content after menu items. Remember to consider the menuPost front matter.

• layouts/partials/menu-footer.html: The footer of the left menu.

You can override other partials from themes/hugo-relearn-themes/, but be careful as this might make future updates more difficult.

Extending Scripts

A common question is how to add extra CSS styles or JavaScript to your site. This depends on what you need.

Adding JavaScript or Stylesheets to All Pages

To add JavaScript files or CSS stylesheets to every page, you can include them in layouts/partials/custom-header.html or layouts/partials/custom-footer.html.

However, this can make your site larger than necessary if these files are only needed on a few pages. The next section explains how to add dependencies only when needed.

Custom Shortcodes with Dependencies

Some shortcodes need extra JavaScript and CSS files. The theme only loads these when the shortcode is used. You can use this for your own shortcodes too.

For example, to create a shortcode called myshortcode that needs the jquery library:

1. Create the shortcode file layouts/shortcodes/myshortcode.html and add the folloging line somewhere:

   ​

   layouts/shortcodes/myshortcode.html

   ...
   {{- .Page.Store.Set "hasMyShortcode" true }}
   ...

2. Option Add this to your hugo.toml:

   hugo.

   toml yaml json

   [params]
     [params.relearn]
       [params.relearn.dependencies]
         [params.relearn.dependencies.myshortcode]
           name = 'MyShortcode'

   params:
     relearn:
       dependencies:
         myshortcode:
           name: MyShortcode

   {
      "params": {
         "relearn": {
            "dependencies": {
               "myshortcode": {
                  "name": "MyShortcode"
               }
            }
         }
      }
   }

3. Create loader file layouts/partials/dependencies/myshortcode.html:

   ​

   layouts/partials/dependencies/myshortcode.html

   {{- if eq .location "footer" }}
     <script src="https://www.unpkg.com/jquery/dist/jquery.js"></script>
   {{- end }}

Important notes:

• Character casing is relevant!
• The name in hugo.toml must match the Store key used in the shortcode file, prefixed with a has.
• The key of relearn.dependencies must match the loader file name.

See the math, mermaid, and openapi shortcodes for examples.

{{- partial "dependencies.gotmpl" (dict "page" . "location" "mylocation") }}

Give a unique name for the location parameter when you call it, so you can distinguish your loaders behavior depending on the location it was called from.

Image Effects

This page shows you, how to configure custom image effects on top of existing ones.

This setting can also be overridden by your front matter.

If you don’t configure anything in your hugo.toml, the image effects default to

Default Values