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

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

This adds a printer ay'con 'n th' topbar. 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
      }
   }
}

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

Logo

Change th' Favicon

If yer favicon be an SVG, PNG, or ICO, just drop yer image 'n yer site’s 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 static/images/favicon-light.svg an' static/images/favicon-dark.svg t' yer site’s directory, respectively, correspond'n t' yer file format. In case some o' th' files be miss'n, th' theme falls back t' favicon.svg fer each miss'n file. All supplied favicons must be o' th' same file format.

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

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

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

Change th' Logo

By default, only yer ship title will be shown at th' top o' th' menu. Ye can configure this, or override th' logo partial.

Create a new file 'n layouts/partials/logo.html o' yer ship. 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!

Th' size o' th' logo will adapt automatically.

Brrrand'n

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

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

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

Shipped Variants

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

• Relearrrn
  • Light: th' classic Relearrrn default, com'n wit' signature green, dark sidebar an' light rrrambl'n area
  • Dark: dark variant o' Light, com'n wit' signature green, dark sidebar an' dark rrrambl'n area
  • Bright: alternative o' Light, com'n wit' signature green, green sidebar an' light rrrambl'n area
• Zen
  • Light: a more relaxed white/grey variant, com'n wit' blue accents, light sidebar an' light rrrambl'n area
  • Dark: dark variant o' Light, com'n wit' blue accents, dark sidebar an' dark rrrambl'n area
• 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 opt'n 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, 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.

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 opt'ns 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 opt'n, ye be defin'n yer theme variants 'n an array but now 'n a t'ble wit' subopt'ns.

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

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

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

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

ye now write it that way:

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

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

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

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

Th' identifier opt'n be mandatory an' equivalent t' th' str'n 'n th' first example. Further opt'ns can be configured, see th' t'ble below.

Parameter

Example Configurat'n

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

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

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

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

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

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

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

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

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

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

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

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

Advanced Topics

Modify'n Variants

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

1. Copy an' change

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

2. Create an' import

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

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

   ​

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

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

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

   hugo.

   toml yaml json

   [params]
     themeVariant = 'my-branding'

   params:
     themeVariant: my-brand'n

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

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

React t' Variant Switches 'n JavaScript

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

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

Module Theming

Change Rules Highlight'n

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

[marrrkup]
  [marrrkup.highlight]
    noClasses = false

marrrkup:
  highlight:
    noClasses: false

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

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

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

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

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

Change 3rd-Party Libraries Them'n

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

• mermaid shortcode
• openapi shortcode

Stylesheet Generrrat'r

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

Download variant Reset variant

Download variant Reset variant

Width

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

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

Chang'n Menu Width

Th' menu width changes fer different screen sizes:

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

T' adjust th' menu width, use these CSS variables. Avast that --MENU-WIDTH-S be fer th' 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

Opt'n Wit' th' default partials fer th' logo, Th' ship title will also 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 linkTitle.

[params]
  linkTitle = 'Relearn'

params:
  linkTitle: Relearrrn

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

Home Button Configurat'n

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

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

[params]
  disableLandingPageButton = true

params:
  disableLandingPageButton: true

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

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

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

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

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

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

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

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

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

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

History

Opt'n Turn on showVisitedLinks=true t' see checkmarks next t' visited planks 'n th' main menu. This also adds a Clear History opt'n at th' bottom o' th' menu t' remove all checkmarks. Avast that checkmarks will disappear if ye rebuild yer ship, as th' plank IDs may change.

[params]
  showVisitedLinks = true

params:
  showVisitedLinks: true

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

Footer

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

Search

Configure Search

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

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

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

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

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

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

params:
  disableSearch: true
  disableSearchIndex: true
  disableSearchPage: true

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

Opt'n Default URLs can be changed wit' th' follow'n parameter

• Search popup: searchindex.js set by searchIndexURL
• Dedicated search plank: 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

Th' Lunr search library doesn’t support all languages o' th' theme. Unsupported languages will show errors 'n th' browser console. Currently unsupported be

• Czech
• Indonesian
• Polish
• Swahili

Mixed Language Support

Opt'n In case yer page’s rrrambl'n contains text 'n multiple languages (for example, ye be writ'n a Piratish documentat'n fer yer English API), ye can set those languages 'n additionalContentLanguage t' broaden th' search.

[params]
  additionalContentLanguage = ['en']

params:
  additionalContentLanguage:
  - en

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

Ye can add multiple languages t' this array.

Shortcut Menu

Th' sidebar contains yer content’s navigat'n menu, but ye can also add extra menu entries or shortcuts 'n a separate section.

For internal links, use th' pageRef property instead o' url. Learrrn more about Hugo’s menu configurat'n.

Title

Opt'n By default, th' shortcut menu has a title ("More" 'n English).

Ye can dis'ble this title wit' disableShortcutsTitle=true.

[params]
  disableShortcutsTitle = true

params:
  disableShortcutsTitle: true

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

T' change th' title, update yer local i18n translat'n file.

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

Single Language Example

Edit hugo.toml an' add [[menu.shortcuts]] entries fer each link:

[menu]
  [[menu.shortcuts]]
    name = 'GitHub Repo'
    pre = '<i class="fa-fw fab fa-github"></i> '
    url = 'https://github.com/McShelby/hugo-theme-relearn'
    weight = 10

  [[menu.shortcuts]]
    name = 'Showcases'
    pageRef = '/showcase'
    weight = 20

  [[menu.shortcuts]]
    name = 'Credits'
    pageRef = '/more/credits'
    weight = 30

  [[menu.shortcuts]]
    name = 'Tags'
    pageRef = '/tags'
    pre = '<i class="fa-fw fas fa-tags"></i> '
    weight = 40

  [[menu.shortcuts]]
    name = 'Categories'
    pageRef = '/categories'
    pre = '<i class="fa-fw fas fa-layer-group"></i> '
    weight = 50

menu:
  shortcuts:
  - name: GitHub Repo
    pre: '<i class="fa-fw fab fa-github"></i> '
    url: https://github.com/McShelby/hugo-theme-relearn
    weight: 10
  - name: Showcases
    pageRef: /showcase
    weight: 20
  - name: Credits
    pageRef: /more/credits
    weight: 30
  - name: Tags
    pageRef: /tags
    pre: '<i class="fa-fw fas fa-tags"></i> '
    weight: 40
  - name: Categories
    pageRef: /categories
    pre: '<i class="fa-fw fas fa-layer-group"></i> '
    weight: 50

{
   "menu": {
      "shortcuts": [
         {
            "name": "GitHub Repo",
            "pre": "\u003ci class=\"fa-fw fab fa-github\"\u003e\u003c/i\u003e ",
            "url": "https://github.com/McShelby/hugo-theme-relearn",
            "weight": 10
         },
         {
            "name": "Showcases",
            "pageRef": "/showcase",
            "weight": 20
         },
         {
            "name": "Credits",
            "pageRef": "/more/credits",
            "weight": 30
         },
         {
            "name": "Tags",
            "pageRef": "/tags",
            "pre": "\u003ci class=\"fa-fw fas fa-tags\"\u003e\u003c/i\u003e ",
            "weight": 40
         },
         {
            "name": "Categories",
            "pageRef": "/categories",
            "pre": "\u003ci class=\"fa-fw fas fa-layer-group\"\u003e\u003c/i\u003e ",
            "weight": 50
         }
      ]
   }
}

Multilingual Example

For multilingual sites, set different menus fer each language 'n hugo.toml:

[languages]
  [languages.en]
    languageName = 'English'
    title = 'Hugo Relearrrn Theme'
    weight = 1

    [languages.en.menu]
      [[languages.en.menu.shortcuts]]
        name = 'GitHub Repo'
        pre = '<i class="fa-fw fab fa-github"></i> '
        url = 'https://github.com/McShelby/hugo-theme-relearn'
        weight = 10

      [[languages.en.menu.shortcuts]]
        name = 'Showcases'
        pageRef = '/showcase'
        weight = 20

      [[languages.en.menu.shortcuts]]
        name = 'Credits'
        pageRef = '/more/credits'
        weight = 30

      [[languages.en.menu.shortcuts]]
        name = 'Tags'
        pageRef = '/tags'
        pre = '<i class="fa-fw fas fa-tags"></i> '
        weight = 40

      [[languages.en.menu.shortcuts]]
        name = 'Categories'
        pageRef = '/categories'
        pre = '<i class="fa-fw fas fa-layer-group"></i> '
        weight = 50

  [languages.pir]
    languageName = 'Arrr! Pirrratish'
    title = 'Captain Hugo Relearrrn Theme'
    weight = 2

    [languages.pir.menu]
      [[languages.pir.menu.shortcuts]]
        identifier = 'ds'
        name = '<i class="fa-fw fab fa-github"></i> GitHub Repo'
        url = 'https://github.com/McShelby/hugo-theme-relearn'
        weight = 10

      [[languages.pir.menu.shortcuts]]
        name = '<i class="fa-fw fas fa-camera"></i> Showcases'
        pageRef = '/showcase'
        weight = 11

      [[languages.pir.menu.shortcuts]]
        name = 'GitHub Repo'
        pre = '<i class="fa-fw fab fa-github"></i> '
        url = 'https://github.com/McShelby/hugo-theme-relearn'
        weight = 10

      [[languages.pir.menu.shortcuts]]
        name = 'Showcases'
        pageRef = '/showcase'
        weight = 20

      [[languages.pir.menu.shortcuts]]
        name = 'Crrredits'
        pageRef = '/more/credits'
        weight = 30

      [[languages.pir.menu.shortcuts]]
        name = 'Arrr! Tags'
        pageRef = '/tags'
        pre = '<i class="fa-fw fas fa-tags"></i> '
        weight = 40

      [[languages.pir.menu.shortcuts]]
        name = 'Categorrries'
        pageRef = '/categories'
        pre = '<i class="fa-fw fas fa-layer-group"></i> '
        weight = 50

languages:
  en:
    languageName: English
    menu:
      shortcuts:
      - name: GitHub Repo
        pre: '<i class="fa-fw fab fa-github"></i> '
        url: https://github.com/McShelby/hugo-theme-relearn
        weight: 10
      - name: Showcases
        pageRef: /showcase
        weight: 20
      - name: Credits
        pageRef: /more/credits
        weight: 30
      - name: Tags
        pageRef: /tags
        pre: '<i class="fa-fw fas fa-tags"></i> '
        weight: 40
      - name: Categories
        pageRef: /categories
        pre: '<i class="fa-fw fas fa-layer-group"></i> '
        weight: 50
    title: Cap'n Hugo Relearrrn Theme
    weight: 1
  pir:
    languageName: Arrr! Pirrratish
    menu:
      shortcuts:
      - identifier: ds
        name: <i class="fa-fw fab fa-github"></i> GitHub Repo
        url: https://github.com/McShelby/hugo-theme-relearn
        weight: 10
      - name: <i class="fa-fw fas fa-camera"></i> Showcases
        pageRef: /showcase
        weight: 11
      - name: GitHub Repo
        pre: '<i class="fa-fw fab fa-github"></i> '
        url: https://github.com/McShelby/hugo-theme-relearn
        weight: 10
      - name: Showcases
        pageRef: /showcase
        weight: 20
      - name: Crrredits
        pageRef: /more/credits
        weight: 30
      - name: Arrr! Tags
        pageRef: /tags
        pre: '<i class="fa-fw fas fa-tags"></i> '
        weight: 40
      - name: Categorrries
        pageRef: /categories
        pre: '<i class="fa-fw fas fa-layer-group"></i> '
        weight: 50
    title: Captain Hugo Relearrrn Theme
    weight: 2

{
   "languages": {
      "en": {
         "languageName": "English",
         "menu": {
            "shortcuts": [
               {
                  "name": "GitHub Repo",
                  "pre": "\u003ci class=\"fa-fw fab fa-github\"\u003e\u003c/i\u003e ",
                  "url": "https://github.com/McShelby/hugo-theme-relearn",
                  "weight": 10
               },
               {
                  "name": "Showcases",
                  "pageRef": "/showcase",
                  "weight": 20
               },
               {
                  "name": "Credits",
                  "pageRef": "/more/credits",
                  "weight": 30
               },
               {
                  "name": "Tags",
                  "pageRef": "/tags",
                  "pre": "\u003ci class=\"fa-fw fas fa-tags\"\u003e\u003c/i\u003e ",
                  "weight": 40
               },
               {
                  "name": "Categories",
                  "pageRef": "/categories",
                  "pre": "\u003ci class=\"fa-fw fas fa-layer-group\"\u003e\u003c/i\u003e ",
                  "weight": 50
               }
            ]
         },
         "title": "Hugo Relearrrn Theme",
         "weight": 1
      },
      "pir": {
         "languageName": "Arrr! Pirrratish",
         "menu": {
            "shortcuts": [
               {
                  "identifier": "ds",
                  "name": "\u003ci class=\"fa-fw fab fa-github\"\u003e\u003c/i\u003e GitHub Repo",
                  "url": "https://github.com/McShelby/hugo-theme-relearn",
                  "weight": 10
               },
               {
                  "name": "\u003ci class=\"fa-fw fas fa-camera\"\u003e\u003c/i\u003e Showcases",
                  "pageRef": "/showcase",
                  "weight": 11
               },
               {
                  "name": "GitHub Repo",
                  "pre": "\u003ci class=\"fa-fw fab fa-github\"\u003e\u003c/i\u003e ",
                  "url": "https://github.com/McShelby/hugo-theme-relearn",
                  "weight": 10
               },
               {
                  "name": "Showcases",
                  "pageRef": "/showcase",
                  "weight": 20
               },
               {
                  "name": "Crrredits",
                  "pageRef": "/more/credits",
                  "weight": 30
               },
               {
                  "name": "Arrr! Tags",
                  "pageRef": "/tags",
                  "pre": "\u003ci class=\"fa-fw fas fa-tags\"\u003e\u003c/i\u003e ",
                  "weight": 40
               },
               {
                  "name": "Categorrries",
                  "pageRef": "/categories",
                  "pre": "\u003ci class=\"fa-fw fas fa-layer-group\"\u003e\u003c/i\u003e ",
                  "weight": 50
               }
            ]
         },
         "title": "Captain Hugo Relearrrn Theme",
         "weight": 2
      }
   }
}

Display'n Planks Only 'n th' Shortcuts Menu

T' show planks only 'n th' shortcuts menu ye have two choices

1. Create a headless branch bundle, _index.md 'n its own folder wit' th' below front matter. Th' branch bundle will not be contained 'n th' 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 plank inside a headless branch bundle wit' th' follow'n front matter 'n th' bundle. This causes th' child but not th' branch bundle t' be contained 'n th' 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"
      }
   }

   Th' child plank can be any type o' rrrambl'n.

   content/more/credits_index.en.md

   toml yaml json

   +++
   title = 'Credits'
   +++

   ---
   title: Credits
   ---

   {
      "title": "Credits"
   }

Width

Th' theme adjusts th' rrrambl'n width when ye resize yer browser.

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

Chang'n th' Main Area’s Maximum Width

Th' main area has a default maximum width o' 80.25rem fer better readability. If ye want t' change this, ye can set a CSS vari'ble

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

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

Titles & Breadcrumbs

Breadcrumbs

Learrrn how t' turn off th' breadcrumbs completely an' further configure th' topbar.

Opt'n Set disableRootBreadcrumb=true t' remove th' root breadcrumb which often feels redundant. This will also apply t' th' breadcrumbs o' th' search results an' taxonomy planks.

Opt'n Ye can override th' default breadcrumb separator by us'n breadcrumbSeparator='/'. This separator will also be used 'n th' breadcrumbs o' th' search results an' taxonomy planks.

Opt'n By default th' term planks o' a taxonomy will display th' breadcrumb fer each plank. Set disableTermBreadcrumbs=true t' remove th' breadcrumb if th' term planks look t' cluttered.

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

params:
  breadcrumbSeparator: /
  disableRootBreadcrumb: true
  disableTermBreadcrumbs: true

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

Titles

Opt'n Ye can override th' default title separator by us'n titleSeparator='|'.

[params]
  titleSeparator = '|'

params:
  titleSeparator: '|'

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

Headings

Head'ns can have anchor links that appear when ye hover over them.

Ye can change what happens when ye click th' anchor ay'con 'n yer hugo.toml file. By default, all opt'ns be turned on. If ye turn off all opt'ns, no anchor ay'con will show up when ye hover.

Copy Anchor Links

Opt'n Set disableAnchorCopy=true t' prevent copy'n th' anchor link when ye click th' ay'con.

[params]
  disableAnchorCopy = true

params:
  disableAnchorCopy: true

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

Scroll t' Head'n

Opt'n Set disableAnchorScrolling=true t' stop th' plank from scroll'n t' th' head'n when ye click th' anchor ay'con.

[params]
  disableAnchorScroll'n = true

params:
  disableAnchorScroll'n: true

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

Linking

Further sett'ns be avail'ble t' be used 'n yer configurat'n or front matter.

URL Management

Opt'n By default, th' theme adds index.html t' plank links when uglyURLs=false (Hugo’s default).

If you’re only us'n a web server scenario an' dislike this, ye can reset t' Hugo’s default behavior by sett'ns disableExplicitIndexURLs=true.

For th' file system scenario, ye be not allowed t' change this value.

[params]
  disableExplicitIndexURLs = true

params:
  disableExplicitIndexURLs: true

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

Patch'n th' relref Shortcode

Opt'n While th' usage o' relref be obsolete an' discouraged by Cap'n Hugo fer a while, exist'n installat'ns may still use it.

In configurat'ns us'n a baseURL wit' a subdirectory an' hav'n relativeURLs=false (the default), Hugo’s standard relref implementat'n be fail'n.

T' work around this, ye can activate a patched version o' th' shortcode by sett'n disableDefaultRelref=true.

[params]
  disableDefaultRelref = true

params:
  disableDefaultRelref: true

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

Hidden Pages

This theme allows ye t' create hidden planks.

Hidden planks be created but not shown 'n th' navigat'n. This be useful fer planks ye only want t' access via a direct link.

When ye visit a hidden page’s URL, it will appear 'n th' navigat'n menu.

Hidden planks can also have hidden subpages, creat'n multiple levels o' hid'n.

By default, hidden planks be only hidden from human visitors. Search engines can still find them by crawl'n yer ship an' th' planks be linked 'n yer taxonomies an' ship search. Ye can prevent this wit' these opt'ns.

Hide from Search

Opt'n T' remove hidden planks from search results, use disableSearchHiddenPages=true.

[params]
  disableSearchHiddenPages = true

params:
  disableSearchHiddenPages: true

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

Hide from Search Engines

Opt'n T' hide planks from search engines by remov'n them from th' sitemap, RSS feed an' make them nofollow, use disableSeoHiddenPages=true.

[params]
  disableSeoHiddenPages = true

params:
  disableSeoHiddenPages: true

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

Hide from Taxonomies

Opt'n T' prevent hidden planks from appear'n on taxonomy an' term planks, use disableTagHiddenPages=true. If this makes a term’s count zero, an empty term plank will still be created but not linked.

[params]
  disableTagHiddenPages = true

params:
  disableTagHiddenPages: true

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

Partials

Us'ble Partials

Ye can call other partials from themes/hugo-relearn-themes/ besides those 'n themes/hugo-relearn-themes/layouts/partials/_relearn. However, us'n partials not mentioned as customiz'ble below might make future updates more challeng'n.

Customiz'ble Partials

Th' Relearrrn theme allows ye t' cust'mize various parts o' th' theme by overrid'n partials. This makes th' theme highly configur'ble.

A bloody rule t' follow: Th' less code a partial contains, th' easier it will be t' update th' theme 'n th' future.

Here’s a list o' partials ye can safely override:

• layouts/partials/content.html: Th' main rrrambl'n o' a plank. Override this t' display additonal plank metadata.

• layouts/partials/content-header.html: Th' header above th' title. By default, it shows tags, but ye can change this.

• layouts/partials/content-footer.html: Th' footer below th' rrrambl'n. By default, it shows author info, modificat'n dates, an' categories. Ye can cust'mize this.

• layouts/partials/custom-header.html: For add'n custom CSS. Remember t' include th' style HTML tag.

• layouts/partials/custom-footer.html: For add'n custom JavaScript. Remember t' include th' script HTML tag.

• layouts/partials/favicon.html: Th' favicon. Ye should definitely cust'mize this.

• layouts/partials/head'n.html: th' page’s title head'ns

• layouts/partials/heading-pre.html: Add rrrambl'n before th' page’s title head'ns. Remember t' consider th' headingPre front matter.

• layouts/partials/heading-post.html: Add rrrambl'n after th' page’s title head'ns. Remember t' consider th' headingPost front matter.

• layouts/partials/logo.html: Th' logo 'n th' top left corner. Ye should cust'mize this.

• layouts/partials/menu-pre.html: Add rrrambl'n before menu items. Remember t' consider th' menuPre front matter.

• layouts/partials/menu-post.html: Add rrrambl'n after menu items. Remember t' consider th' menuPost front matter.

• layouts/partials/menu-footer.html: Th' footer o' th' left menu.

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

Extending Scripts

A common quest'n be how t' add extra CSS styles or JavaScript t' yer ship. This depends on what ye need.

Add'n JavaScript or Stylesheets t' All Planks

T' add JavaScript files or CSS stylesheets t' every plank, ye can include them 'n layouts/partials/custom-header.html or layouts/partials/custom-footer.html.

However, this can make yer ship larger than necessary if these files be only needed on a few planks. Th' next section explains how t' add dependencies only when needed.

Custom Shorrrtcodes wit' Dependencies

Some shorrrtcodes need extra JavaScript an' CSS files. Th' theme only loads these when th' shortcode be used. Ye can use this fer yer own shorrrtcodes too.

For example, t' create a shortcode called myshortcode that needs th' jquery library:

1. Create th' shortcode file layouts/shortcodes/myshortcode.html an' add th' follog'n line somewhere:

   ​

   layouts/shortcodes/myshortcode.html

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

2. Opt'n Add this t' yer 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 .locat'n "footer" }}
     <script src="https://www.unpkg.com/jquery/dist/jquery.js"></script>
   {{- end }}

Important notes:

• Character cas'n be relevant!
• Th' name 'n hugo.toml must match th' Store key used 'n th' shortcode file, prefixed wit' a has.
• Th' key o' relearn.dependencies must match th' loader file name.

See th' math, mermaid, an' openapi shorrrtcodes fer examples.

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

Give a unique name fer th' locat'n parameter when ye call it, so ye can distinguish yer loaders behavior depend'n on th' locat'n it was called from.

Image Effects

This plank shows ye, how t' configure custom image effects on top o' exist'n ones.

This sett'n can also be overridden by yer front matter.

If ye don’t configure anyth'n 'n yer hugo.toml, th' image effects default t'

Default Values

[imageEffects]
  border = false
  lazy = true
  lightbox = true
  shadow = false

imageEffects:
  border: false
  lazy: true
  lightbox: true
  shadow: false

{
   "imageEffects": {
      "border": false,
      "lazy": true,
      "lightbox": true,
      "shadow": false
   }
}

Configurat'n

Opt'n Ye can change these sett'ns 'n yer hugo.toml an' add arbitrary custom effects as boolean values (like bg-white 'n th' below snippet).

[params]
  [params.imageEffects]
    bg-white = true
    border = true
    lazy = false

params:
  imageEffects:
    bg-white: true
    border: true
    lazy: false

{
   "params": {
      "imageEffects": {
         "bg-white": true,
         "border": true,
         "lazy": false
      }
   }
}

This would result 'n

[imageEffects]
  bg-white = true
  border = true
  lazy = false
  lightbox = true
  shadow = false

imageEffects:
  bg-white: true
  border: true
  lazy: false
  lightbox: true
  shadow: false