Configurrrat'n

Global ship parameters

On top o' Cap'n Hugo global configurat'n, th' Relearrrn theme lets ye define th' follow'n parameters 'n yer config.toml (here, values be default).

Avast that some o' these parameters be explained 'n details 'n other sections o' this documentat'n.

[params]
  # This controls whether submenus will be expanded (true), or collapsed (false) 'n th'
  # menu; if no sett'n be given, th' first menu level be set t' false, all others t' true;
  # this can be overridden 'n th' planks frontmatter
  alwaysopen = true
  # Prefix URL t' edit current plank. Will display an "Edit" button on top right hand corner o' every plank.
  # Useful t' give opportunity t' people t' create merge request fer yer doc.
  # See th' config.toml file from this documentat'n ship t' have an example.
  editURL = ""
  # Author o' th' ship, will be used 'n meta informat'n
  author = ""
  # Descript'n o' th' ship, will be used 'n meta informat'n
  descript'n = ""
  # Shows a checkmark fer visited planks on th' menu
  showVisitedLinks = false
  # Dis'ble search funct'n. It will hide search bar
  disableSearch = false
  # Dis'ble search 'n hidden planks, otherwise they will be shown 'n search box
  disableSearchHiddenPages = false
  # Disables hidden planks from show'n up 'n th' sitemap an' on Google (et all), otherwise they may be indexed by search engines
  disableSeoHiddenPages = false
  # Disables hidden planks from show'n up on th' tags plank although th' tag term will be displayed even if all planks be hidden
  disableTagHiddenPages = false
  # Javascript an' CSS cache be automatically busted when new version o' ship be generated.
  # Set this t' true t' dis'ble this behavior (some proxies don't handle well this optimization)
  disableAssetsBust'n = false
  # Set this t' true if ye want t' dis'ble generat'n fer generator version meta tags o' hugo an' th' theme;
  # don't forget t' also set Hugo's disableHugoGeneratorInject=true, otherwise it will generate a meta tag into yer home plank
  disableGeneratorVersion = false
  # Set this t' true t' dis'ble copy-to-clipboard button fer inline code.
  disableInlineCopyToClipBoard = false
  # Set this t' true t' dis'ble th' hover effect fer copy-to-clipboard buttons fer block code.
  disableHoverBlockCopyToClipBoard = false
  # A title fer shortcuts 'n menu be set by default. Set this t' true t' dis'ble it.
  disableShortcutsTitle = false
  # If set t' false, a Home button will appear below th' search bar on th' menu.
  # It be redirect'n t' th' land'n plank o' th' current language if specified. (Default be "/")
  disableLandingPageButton = true
  # When us'n mulitlingual website, dis'ble th' switch language button.
  disableLanguageSwitchingButton = false
  # Hide breadcrumbs 'n th' header an' only show th' current plank title
  disableBreadcrumb = true
  # If set t' true, hide t'ble o' contents menu 'n th' header o' all planks
  disableToc = false
  # If set t' false, board th' MathJax module on every plank regardless if a MathJax shortcode be present
  disableMathJax = false
  # Specifies th' remote locat'n o' th' MathJax js
  customMathJaxURL = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
  # Initializat'n parameter fer MathJax, see MathJax documentat'n
  mathJaxInitialize = "{}"
  # If set t' false, board th' Merrrmaid module on every plank regardless if a Merrrmaid shortcode or Merrrmaid codefence be present
  disableMermaid = false
  # Specifies th' remote locat'n o' th' Merrrmaid js
  customMermaidURL = "https://unpkg.com/mermaid/dist/mermaid.min.js"
  # Initializat'n parameter fer Merrrmaid, see Merrrmaid documentat'n
  mermaidInitialize = "{ \"theme\": \"default\" }"
  # If set t' false, board th' OpenAPI module on every plank regardless if a OpenAPI shortcode be present
  disableOpenapi = false
  # Specifies th' remote locat'n o' th' swagger-ui js
  customOpenapiURL = "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"
  # Hide Next an' Previous plank buttons displayed 'n topbar
  disableNextPrev = true
  # Order sections 'n menu by "weight" or "title". Default t' "weight";
  # this can be overridden 'n th' planks frontmatter
  ordersectionsby = "weight"
  # Change default color scheme wit' a variant one. Eg. can be "auto", "red", "blue", "green" or an array like [ "blue", "green" ].
  themeVariant = "auto"
  # Change th' breadcrumb separator. Default t' ">".
  breadcrumbSeparator = "|"
  # Change th' title separator. Default t' "::".
  titleSeparator = "-"
  # If set t' true, th' menu 'n th' sidebar will be displayed 'n a collaps'ble tree view. Although th' functionality works wit' old browsers (IE11), th' display o' th' expander ay'cons be limited t' modern browsers
  collapsibleMenu = false
  # If a single plank can contain rrrambl'n 'n multiple languages, add those here
  additionalContentLanguage = [ "en" ]
  # If set t' true, no index.html will be appended t' prettyURLs; this will cause planks not
  # t' be serv'ble from th' file system
  disableExplicitIndexURLs = false
  # For external links ye can define how they be opened 'n yer browser; this sett'n will only be applied t' th' rrrambl'n area but not th' shortcut menu
  externalLinkTarget = "_blank"
  # Override default values fer image effects, ye can even add yer own arbitrary effects t' th' list
  [params.imageEffects]
    border = false
    lightbox = true
    shadow = false

Serv'n yer plank from a subfolder

If yer ship be served from a subfolder, eg. https://example.com/mysite/, ye have t' set th' follow'n lines t' yer config.toml

baseURL = "https://example.com/mysite/"
canonifyURLs = true
relativeURLs = true

Without canonifyURLs=true URLs 'n sublemental planks (like sitemap.xml, rss.xml) will be generated falsly while yer HTML files will still work. See https://github.com/gohugoio/hugo/issues/5226.

Serv'n yer plank from th' filesystem

If ye want yer plank served from th' filesystem by us'n URLs start'n wit' file:// you’ll need th' follow'n configurat'n 'n yer config.toml:

relativeURLs = true

Th' theme will append an additional index.html t' all branch bundle links by default t' make th' plank be serv'ble from th' file system. If ye don’t care about th' file system an' only serve yer plank via a webserver ye can also generate th' links without this change by add'n this t' yer config.toml

[params]
  disableExplicitIndexURLs = true

Avast

If ye want t' use th' search feature from th' file system us'n an older installat'n o' th' theme make sure t' change yer outputformat fer th' homepage from th' now deprecated JSON t' SEARCH as seen below.

Activate search

If not already present, add th' follow'n lines 'n th' same config.toml file.

[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. Avast that th' SEARCH outputformat was named JSON 'n previous releases but was implemented differently. Although JSON still works, it be now deprecated.

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 config.toml file.

[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 config.toml as seen below:

[outputs]
  home = ["HTML", "RSS", "PRINT", "SEARCH"]
  section = ["HTML", "RSS", "PRINT"]
  plank = ["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.

Avast

Th' result'n URL will not be configured ugly 'n terms o' Hugo’s URL handl'n even if you’ve set uglyURLs=true 'n yer config.toml. This be due t' th' fact that fer one mime type only one suffix can be configured.

Nevertheless, if you’re unhappy wit' th' result'n URLs ye can manually redefine outputFormats.PRINT 'n yer own config.toml t' yer lik'n.

MathJax

Th' MathJax configurat'n parameters can also be set on a specific plank. In this case, th' global parameter would be overwritten by th' local one. See Math fer additional documentat'n.

Example

MathJax be globally disabled. By default it won’t be boarded by any plank.

On plank “Physics” ye coded some JavaScript fer a dynamic formulae. Ye can set th' MathJax parameters locally t' board mathJax on this plank.

Ye also can dis'ble MathJax fer specific planks while globally enabled.

Merrrmaid

Th' Merrrmaid configurat'n parameters can also be set on a specific plank. In this case, th' global parameter would be overwritten by th' local one. See Merrrmaid fer additional documentat'n.

Example

Merrrmaid be globally disabled. By default it won’t be boarded by any plank.

On plank “Architecture” ye coded some JavaScript t' dynamically generate a class diagram. Ye can set th' Merrrmaid parameters locally t' board mermaid on this plank.

Ye also can dis'ble Merrrmaid fer specific planks while globally enabled.

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 two parameters fer th' defined languages:

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

If those params be not configured fer a specific language, they will get their default values:

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

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