Directory Structure

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

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

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

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

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

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

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

Multilingual

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

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

Translat'n by File Name

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

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

   hugo.

   toml yaml json

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

   ├── rrrambl'n
   │   ├── 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

Translat'n by Rrrambl'n Directory

Th' theme also support translat'ns by rrrambl'n directory which can be configured 'n a similar way. This be not used 'n further examples o' this documentat'n.

Search Sett'ns

Check th' search configurat'n fer multilingual opt'ns.

Turn Off Language Switch'n

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

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

[params]
  disableLanguageSwitchingButton = true

params:
  disableLanguageSwitchingButton: true

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

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

Ship Title

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

title = 'Hugo Relearrrn Theme'

title: Cap'n Hugo Relearrrn Theme

{
   "title": "Hugo Relearrrn Theme"
}

Ship Descript'n

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

Social Media Images

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

images = ['images/hero.png']

images:
- images/hero.png

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

More Social Media Opt'ns

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

Deployment Scenarios

Offline Usage

Th' theme be us'ble offline. No internet connect'n be required t' board yer plank. This be achieved by stor'n all dependencies within th' theme.

No calls t' 3rd party servers, no call'n home, no track'n. Privacy friendly.

Server Deployment

If yer server deployment has no special requirements, ye can skip this section an' use th' standard Cap'n Hugo opt'ns.

For special requirements, th' theme be cap'ble o' different scenarios, requir'n th' follow'n mandatory sett'ns 'n yer hugo.toml. All sett'ns not mentioned 'n th' examples below can be set t' yer lik'n.

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 ye be still us'n Hugo’s relref shortcode (which ye shouldn’t), ye will need further configurat'n.

Private Web Server (LAN)

Th' same sett'ns as wit' any o' th' public web server scenarios or

baseURL = '/'
relativeURLs = true

baseURL: /
relativeURLs: true

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

File System

Yer generated ship can be used headless without a HTTP server.

This can be achieved by us'n th' file:// protocol 'n yer browser’s address bar or by do'ble click on a generated *.html file 'n yer file navigat'n tool.

Use th' follow'n sett'ns

baseURL = '/'
relativeURLs = true

baseURL: /
relativeURLs: true

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

Available Output Formats

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

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

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

Print Support

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

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

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

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

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

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

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

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

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

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

Marrrkdown Support

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

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

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

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

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

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

Source Support

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

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

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

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

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

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

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

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

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

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

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

Stable Output

Disabl'n th' Generator Meta

Opt'n Th' theme adds a meta tag wit' its version number t' each plank.

This isn’t a security risk an' helps us support ye better.

T' turn this off, set disableGeneratorVersion=true.

[params]
  disableGeneratorVersion = true

params:
  disableGeneratorVersion: true

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

If ye also want t' turn off Hugo’s version meta tag, use disableHugoGeneratorInject=true.

Disabl'n IDs fer Referenced Assets

Opt'n Th' theme creates a unique ID fer each build an' adds it t' each referenced asset’s URL t' make browsers not keep outdated cached assets.

This be bloody fer product'n sites but can be problematic dur'n development. It makes compar'n outputs difficult as each build has new IDs.

T' dis'ble this, set disableAssetsBusting=true.

[params]
  disableAssetsBust'n = true

params:
  disableAssetsBust'n: true

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

Disabl'n IDs fer Interactive HTML Elements

Opt'n Features like expanders, callouts, an' tabs use unique IDs t' work. These IDs change wit' each build.

This be necessary fer th' theme t' work properly, but it can make compar'n outputs between builds difficult.

T' turn this off, set disableRandomIds=true. Avast, that this will result 'n a non-functional ship!.

[params]
  disableRandomIds = true

params:
  disableRandomIds: true

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

Disabl'n Assets Minificat'n

Opt'n If minify=true, further theme assets will be minified dur'n build. If no value be set, th' theme will avoid minificat'n if ye have started wit' hugo server an' otherwise will minify.

[params]
  minify = false

params:
  minify: false

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