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

Disabling Assets Minification

Option If minify=true, further theme assets will be minified during build. If no value is set, the theme will avoid minification if you have started with hugo server and otherwise will minify.

[params]
  minify = false

params:
  minify: false

{
   "params": {
      "minify": false
   }
}