Customizat'n

Usage scenarios

Th' theme be us'ble 'n different scenarios, requir'n th' follow'n mandatory sett'ns 'n yer hugo.toml. All sett'ns not mentioned 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
}

Private Web Server (LAN)

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

baseURL = '/'
relativeURLs = true

baseURL: /
relativeURLs: true

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

File System

baseURL = '/'
relativeURLs = true

baseURL: /
relativeURLs: true

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

[params]
  disableExplicitIndexURLs = true

params:
  disableExplicitIndexURLs: true

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

Activate search

If not already present, add th' follow'n lines 'n yer hugo.toml file.

[outputs]
  home = ['html', 'rss', 'search']

outputs:
  home:
  - html
  - rss
  - search

{
   "outputs": {
      "home": [
         "html",
         "rss",
         "search"
      ]
   }
}

This will generate a search index file at th' root o' yer public folder ready t' be consumed by th' Lunr search library.

Activate dedicated search plank

Ye can add a dedicated search plank fer yer plank by add'n th' searchpage outputformat t' yer home plank by add'n th' follow'n lines 'n yer hugo.toml file. This will cause Cap'n Hugo t' generate a new file http://example.com/mysite/search.html.

[outputs]
  home = ['html', 'rss', 'search', 'searchpage']

outputs:
  home:
  - html
  - rss
  - search
  - searchpage

{
   "outputs": {
      "home": [
         "html",
         "rss",
         "search",
         "searchpage"
      ]
   }
}

Ye can access this plank by either click'n on th' magnifier glass or by typ'n some search term an' press'n ENTER inside o' th' menu’s search box .

Activate print support

Ye can activate print support t' add th' capability t' print whole chapters or even th' complete ship. Just add th' print output format t' yer home, section an' plank 'n yer hugo.toml as seen below:

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

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

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

This will add a little printer ay'con 'n th' top bar. It will switch th' plank t' print preview when clicked. Ye can then send this plank t' th' printer by us'n yer browser’s usual print functionality.

Home Button Configurat'n

If th' disableLandingPageButton opt'n be set t' false, a Home button will appear on th' left menu. It be an alternative fer click'n on th' logo. T' edit th' appearance, ye will have t' configure th' landingPageName fer th' 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 be not configured fer a specific language, they will get their default values:

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

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

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

Th' home button be go'n t' look like this:

Social Media Meta Tags

Ye can add social media meta tags fer th' Open Graph protocol an' Twitter Cards t' yer ship. These be configured as mentioned 'n th' Cap'n Hugo docs.

Change th' Menu Width

Th' menu width adjusts automatically fer different screen sizes.

Th' values fer th' screen width breakpoints aren’t configur'ble.

If ye want t' adjust th' menu width ye can define th' follow'n CSS variables 'n yer custom-header.html. Avast that --MENU-WIDTH-S applies t' th' menu flyout width 'n mobile mode fer small screen sizes.

:root {
    --MENU-WIDTH-S: 14.375rem;
    --MENU-WIDTH-M: 14.375rem;
    --MENU-WIDTH-L: 18.75rem;
}

Change th' Main Area’s Max Width

By default th' main area width will only grow t' a certain extent if more vertical screen space be avail'ble. This be done fer readability purposes as long line be usually harder t' read.

If ye be unhappy wit' th' default, ye can define th' follow'n CSS vari'ble 'n yer custom-header.html an' set th' value t' yer lik'n. If ye want t' use all avail'ble space, select a really big value like 1000rem;

:root {
    --MAIN-WIDTH-MAX: 80.25rem;
}

Change Head'n Anchor Behavior

Each head'n may have an anchor link that be displayed when th' head'n be hovered.

Th' behavior what should happen if th' anchor ay'con be clicked be configur'ble 'n yer hugo.toml. By default all opt'ns be activated. If ye deactivate all opt'ns, no link will be shown on hover.

[params]
  disableAnchorCopy = false
  disableAnchorScroll'n = false

params:
  disableAnchorCopy: false
  disableAnchorScroll'n: false

{
   "params": {
      "disableAnchorCopy": false,
      "disableAnchorScrolling": false
   }
}

disableAnchorCopy

If set t' true, this disables th' copy'n o' anchor links t' th' clipboard.

disableAnchorScroll'n

If set t' true, this disables th' scroll'n t' th' beginn'n o' th' head'n when clicked.

Own Shorrrtcodes wit' JavaScript Dependencies

Certain shorrrtcodes make use o' additional dependencies like JavaScript an' CSS files. Th' theme only loads these dependencies if th' shortcode be used. T' do so correctly th' theme adds management code 'n various files.

Ye can ye use this mechanism 'n yer own shorrrtcodes. Say ye want t' add a shortcode myshortcode that also requires th' jquery JavaScript library.

1. Write th' shortcode file layouts/shortcodes/myshortcode.html an' add th' follow'n line

   ​

   layouts/shortcodes/myshortcode.html

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

2. Add th' follow'n snippet 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. Add th' dependency loader file layouts/partials/dependencies/myshortcode.html. Th' loader file will be called from multiple locat'ns inside o' th' theme wit' th' parameter plank contain'n th' current plank vari'ble an' locat'n wit' one o' th' currently defined locat'ns

   • header: if called at th' end o' th' HTML head element
   • footer: if called at th' end o' th' HTML body element
   ​

   layouts/partials/dependencies/myshortcode.html

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

Character cas'n be relevant!

• th' name sett'n 'n yer hugo.toml must match th' key (that needs t' be prefixed wit' a has) ye used fer th' store 'n yer layouts/shortcodes/myshortcode.html.
• th' key on params.relearn.dependencies 'n yer hugo.toml must match th' base file name o' yer loader file.

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

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

Output Formats

Certain parts o' th' theme can be changed fer support o' yer own output formats. Eg. if ye define a new output format PLAINTEXT 'n yer hugo.toml, ye can add a file layouts/partials/header.plaintext.html t' change th' way, th' plank header should look like fer that output format.

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`
});

Partials

Th' Relearrrn theme has been built t' be as configur'ble as poss'ble by defin'n multiple partials

In themes/hugo-theme-relearn/layouts/partials/, ye will find all th' partials defined fer this theme. If ye need t' overwrite someth'n, don’t change th' code directly. Instead follow this plank. You’d create a new partial 'n th' layouts/partials folder o' yer local project. This partial will have th' priority.

This theme defines th' follow'n partials :

• header.html: th' header o' th' plank. See output-formats
• footer.html: th' footer o' th' plank. See output-formats
• body.html: th' body o' th' plank. Th' body may contain o' one or many articles. See output-formats
• article.html: th' output fer a single article, can contain elements around yer rrrambl'n. See output-formats
• menu.html: left menu. Not meant t' be overwritten
• search.html: search box. Not meant t' be overwritten
• custom-header.html: custom headers 'n plank. Meant t' be overwritten when add'n CSS imports. Don’t forget t' include style HTML tag directive 'n yer file.
• custom-footer.html: custom footer 'n plank. Meant t' be overwritten when add'n JavaScript. Don’t forget t' include javascript HTML tag directive 'n yer file.
• favicon.html: th' favicon
• head'n.html: side-wide configurat'n t' change th' planks title head'ns.
• heading-pre.html: side-wide configurat'n t' prepend t' planks title head'ns. If ye override this, it be yer responsibility t' take th' page’s headingPre sett'n into account.
• heading-post.html: side-wide configurat'n t' append t' planks title head'ns. If ye override this, it be yer responsibility t' take th' page’s headingPost sett'n into account.
• logo.html: th' logo, on top left hand corner
• meta.html: HTML meta tags, if ye want t' change default behavior
• menu-pre.html: side-wide configurat'n t' prepend t' menu items. If ye override this, it be yer responsibility t' take th' page’s menuPre sett'n into account.
• menu-post.html: side-wide configurat'n t' append t' menu items. If ye override this, it be yer responsibility t' take th' page’s menuPost sett'n into account.
• menu-footer.html: footer o' th' left menu
• toc.html: t'ble o' contents
• rrrambl'n.html: th' rrrambl'n plank itself. This can be overridden if ye want t' display page’s meta data above or below th' rrrambl'n.
• content-header.html: header above th' title, has a default implementat'n but ye can overwrite it if ye don’t like it.
• content-footer.html: footer below th' rrrambl'n, has a default implementat'n but ye can overwrite it if ye don’t like it.