Frrrontmatter

Each Cap'n Hugo plank has t' define a frontmatter.

All Frontmatter Opt'ns

Th' values reflect example opt'ns. Th' defaults can be taken from th' annotated example below.

+++
LastModifierDisplayName = ''
LastModifierEmail = ''
alwaysopen = ''
collapsibleMenu = true
customMathJaxURL = ''
customMermaidURL = ''
customOpenapiURL = ''
descript'n = ''
disableBreadcrumb = false
disableMathJax = true
disableMermaid = true
disableNextPrev = false
disableOpenapi = true
disableToc = false
editURL = ''
headingPost = ''
headingPre = ''
hidden = false
highlightWrap = true
images = ['images/hero.png']
mathJaxInitialize = '{}'
menuPost = ''
menuPre = ''
mermaidInitialize = '{ "securityLevel": "loose" }'
mermaidZoom = true
ordersectionsby = 'weight'
title = 'Example Page'

[image]
  errorlevel = ''

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

[include]
  errorlevel = ''

[link]
  errorlevel = ''

[openapi]
  errorlevel = ''
+++
---
LastModifierDisplayName: ""
LastModifierEmail: ""
alwaysopen: ""
collapsibleMenu: true
customMathJaxURL: ""
customMermaidURL: ""
customOpenapiURL: ""
descript'n: ""
disableBreadcrumb: false
disableMathJax: true
disableMermaid: true
disableNextPrev: false
disableOpenapi: true
disableToc: false
editURL: ""
headingPost: ""
headingPre: ""
hidden: false
highlightWrap: true
image:
  errorlevel: ""
imageEffects:
  border: true
  lazy: true
  lightbox: true
  shadow: false
images:
- images/hero.png
include:
  errorlevel: ""
link:
  errorlevel: ""
mathJaxInitialize: '{}'
menuPost: ""
menuPre: ""
mermaidInitialize: '{ "securityLevel": "loose" }'
mermaidZoom: true
openapi:
  errorlevel: ""
ordersectionsby: weight
title: Example Plank
---
{
   "LastModifierDisplayName": "",
   "LastModifierEmail": "",
   "alwaysopen": "",
   "collapsibleMenu": true,
   "customMathJaxURL": "",
   "customMermaidURL": "",
   "customOpenapiURL": "",
   "description": "",
   "disableBreadcrumb": false,
   "disableMathJax": true,
   "disableMermaid": true,
   "disableNextPrev": false,
   "disableOpenapi": true,
   "disableToc": false,
   "editURL": "",
   "headingPost": "",
   "headingPre": "",
   "hidden": false,
   "highlightWrap": true,
   "image": {
      "errorlevel": ""
   },
   "imageEffects": {
      "border": true,
      "lazy": true,
      "lightbox": true,
      "shadow": false
   },
   "images": [
      "images/hero.png"
   ],
   "include": {
      "errorlevel": ""
   },
   "link": {
      "errorlevel": ""
   },
   "mathJaxInitialize": "{}",
   "menuPost": "",
   "menuPre": "",
   "mermaidInitialize": "{ \"securityLevel\": \"loose\" }",
   "mermaidZoom": true,
   "openapi": {
      "errorlevel": ""
   },
   "ordersectionsby": "weight",
   "title": "Example Page"
}

Annotated Frontmatter Opt'ns

+++
# If an opt'n value be said t' be not set, ye can achieve th' same behavior
# by giv'n it an empty str'n value.

###############################################################################
# Cap'n Hugo
# These opt'ns usually apply t' other themes as well.

# Th' social media image o' yer plank.
# Default: not set
# This be used fer generat'n social media meta informat'n fer th' opengraph
# protocol an' twitter cards.
# If not set, th' set value o' yer site's hugo.toml be used.
images = [ "images/hero.png" ]

# Th' title o' yer plank.
# Default: not set
# A plank without a title be treated as a hidden plank.
title = "Example Page"

# Th' descript'n o' yer plank.
# Default: not set
# This be used fer generat'n HTML meta tags, social media meta informat'n
# fer th' opengraph protocol an' twitter cards.
# If not set, th' set value o' yer site's hugo.toml be used fer th' html
# meta tag, social media meta informat'n fer th' opengraph protocol an'
# twitter cards.
descript'n = ""

###############################################################################
# Relearrrn Theme
# These opt'ns be specific t' th' Relearrrn theme.

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Topbar
# These opt'ns modify th' topbar appearance.

# Hide th' t'ble o' contents button.
# Default: false
# If th' TOC button be hidden, also th' keyboard shortcut be disabled.
# If not set, th' set value o' yer site's hugo.toml be used.
disableToc = false

# Hide th' breadcrumbs.
# Default: false
# If th' breadcrumbs be hidden, th' title o' th' displayed plank will still be
# shown 'n th' topbar.
disableBreadcrumb = false

# Hide Next an' Previous navigat'n buttons.
# Default: false
# If th' navigat'n buttons be hidden, also th' keyboard shortcuts be
# disabled.
disableNextPrev = false

# Th' URL prefix t' edit a plank.
# Default: not set
# If set, an edit button will be shown 'n th' topbar. If th' button be hidden,
# also th' keyboard shortcuts be disabled. Th' value can contain th' macro
# `${FilePath}` which will be replaced by th' file path o' yer displayed plank.
# If not set, th' set value o' yer site's hugo.toml be used. If th' global
# parameter be given but ye want t' hide th' button fer th' displayed plank,
# ye can set th' value t' an empty str'n. If instead o' hid'n ye want t' have
# an disabled button, ye can set th' value t' a str'n contain'n just spaces.
# This be useful if ye want t' give th' opportunity fer people t' create merge
# request fer yer rrrambl'n.
editURL = ""

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Menu
# These opt'ns modify th' menu appearance.

# Prefix fer th' title 'n main menu.
# Default: not set
# Th' title o' th' plank 'n th' menu will be prefixed by this HTML rrrambl'n.
menuPre = ""

# Suffix fer th' title 'n main menu.
# Default: not set
# Th' title o' th' plank 'n th' menu will be suffixed by this HTML rrrambl'n.
menuPost = ""

# Th' order o' main menu submenus.
# Default: "weight"
# Submenus can be ordered by "weight", "title", "linktitle", "modifieddate",
# "expirydate", "publishdate", "date", "length" or "default" (adher'n t'
# Hugo's default sort order).
# If not set, th' value o' th' parent menu entry be used.
ordersectionsby = "weight"

# Th' initial expand state o' submenus.
# Default: not set
# This controls whether submenus will be expanded (true), or collapsed (false)
# 'n th' menu. If not set, th' first menu level be set t' false, all others
# levels be set t' true. If not set, th' value o' th' parent menu entry be used.
# If th' displayed plank has submenus, they will always been displayed expanded
# regardless o' this opt'n.
alwaysopen = ""

# Shows expander fer submenus.
# Default: false
# If set t' true, a submenu 'n th' sidebar will be displayed 'n a collaps'ble
# tree view an' a click'ble expander be set 'n front o' th' entry.
# If not set, th' set value o' yer site's hugo.toml be used.
collapsibleMenu = true

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Hidden planks
# These opt'ns configure how hidden planks be treated.
# A plank flagged as hidden, be only removed from th' main menu if ye be
# currently not on this plank or th' hidden plank be not part o' current page's
# ancestors. For all other functionality 'n Hugo a hidden plank behaves like any
# other plank if not otherwise configured.

# Hide a page's menu entry.
# Default: false
# If this value be true, th' plank be hidden from th' menu.
hidden = false

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Rrrambl'n
# These opt'ns modify how yer rrrambl'n be displayed.

# Prefix fer th' title 'n th' rrrambl'n area.
# Default: not set
# Th' title o' th' plank head'n will be prefixed by this HTML rrrambl'n.
headingPre = ""

# Suffix fer th' title 'n th' rrrambl'n area.
# Default: not set
# Th' title o' th' plank head'n will be suffixed by this HTML rrrambl'n.
headingPost = ""

# Display name o' th' page's last editor.
# Default: not set
# If set, it will be displayed 'n th' default footer.
LastModifierDisplayName = ""

# Email address o' th' page's last editor.
# Default: not set
# If set together wit' LastModifierDisplayName, it will be displayed 'n th'
# default footer.
LastModifierEmail = ""

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Highlight
# These opt'ns configure how code be displayed.

# Wrap fer code blocks.
# Default: true
# By default lines o' code blocks wrap around if th' line be too long t' be
# displayed on screen. If ye dislike this behavior, ye can reconfigure it
# here.
# Avast that lines always wrap 'n print mode regardless o' this opt'n.
# If not set, th' set value o' yer site's hugo.toml be used or given as a
# parameter t' individual code blocks.
highlightWrap = true

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Include
# These opt'ns configure how th' include shortcode works.

# What t' do when path be not resolved.
# Default: ""
# Ye can control what should happen if a path can not be resolved t' as
# a resource or via th' file system. If not set, no output will be written
# fer th' unresolved path. If set t' `warning` th' same happens an' an additional
# warning be printed. If set t' `error` an error message be printed an' th' build
# be aborted.
# If not set, th' set value o' yer site's hugo.toml be used.
include.errorlevel = ""

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Images
# These opt'ns configure how images be displayed.

# What t' do when local image link be not resolved.
# Default: ""
# Ye can control what should happen if a local image can not be resolved t' as
# a resource. If not set, th' unresolved link be written as given into th' result'n
# output. If set t' `warning` th' same happens an' an additional warning be
# printed. If set t' `error` an error message be printed an' th' build be
# aborted.
# Please note that this can not resolve files inside o' yer `static` directory.
# If not set, th' set value o' yer site's hugo.toml be used.
image.errorlevel = ""

# Image effects.
# See th' documentat'n fer how ye can even add yer own arbitrary effects t'
# th' list.
# All effect values default t' th' values o' yer site's hugo.toml an' can be
# overridden through URL parameter given t' th' image. See th' documentat'n fer
# details.

# Default: false
imageEffects.border = true
# Default: true
imageEffects.lazy = true
# Default: true
imageEffects.lightbox = true
# Default: false
imageEffects.shadow = false

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Links
# These opt'ns configure how links be displayed.

# What t' do when local plank link be not resolved.
# Default: ""
# Ye can control what should happen if a local link can not be resolved t' a
# plank. If not set, th' unresolved link be written as given into th' result'n
# output. If set t' `warning` th' same happens an' an additional warning be
# printed. If set t' `error` an error message be printed an' th' build be
# aborted.
# Please note that wit' Cap'n Hugo < 0.123.0 + `uglyURLs=true` this can lead t' false
# negatives.
# If not set, th' set value o' yer site's hugo.toml be used.
link.errorlevel = ""

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# MathJax
# These opt'ns configure how math formulae be displayed.

# Initializat'n opt'ns fer MathJax.
# Default: not set
# A JSON value. See th' MathJaxdocumentat'n fer poss'ble parameter.
# If not set, th' set value o' yer site's hugo.toml be used.
mathJaxInitialize = "{}"

# Only board MathJax if needed.
# Default: true
# If a Math shortcode be found, th' opt'n will be ignored an'
# MathJax will be boarded regardlessly. Th' opt'n be still useful 'n case ye
# be us'n script'n t' set up yer graph. In this case no shortcode or
# codefence be involved an' th' library be not boarded by default. In this case
# ye can set `disableMathJax=false` 'n yer frontmatter t' force th' library t'
# be boarded.
# If not set, th' set value o' yer site's hugo.toml be used.
disableMathJax = true

# URL fer external MathJax library.
# Default: not set
# Specifies th' remote locat'n o' th' MathJax library. By default th' shipped
# version will be used.
# If not set, th' set value o' yer site's hugo.toml be used.
customMathJaxURL = "" # "https://unpkg.com/mathjax/es5/tex-mml-chtml.js"

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# Merrrmaid
# These opt'ns configure how Merrrmaid graphs be displayed.

# Make graphs pan'ble an' zoom'ble
# Default: false
# For huge graphs it can be helpful t' make them zoom'ble. Zoom'ble graphs come
# wit' a reset button fer th' zoom.
# If not set, th' set value o' yer site's hugo.toml be used or given as a
# parameter t' individual graphs.
mermaidZoom = true

# Initializat'n opt'ns fer Merrrmaid.
# Default: not set
# A JSON value. See th' Merrrmaid documentat'n fer poss'ble parameter.
# If not set, th' set value o' yer site's hugo.toml be used.
mermaidInitialize = "{ \"securityLevel\": \"loose\" }"

# Only board Merrrmaid if needed.
# Default: true
# If a Merrrmaid shortcode or codefence be found, th' opt'n will be ignored an'
# Merrrmaid will be boarded regardlessly. Th' opt'n be still useful 'n case ye
# be us'n script'n t' set up yer graph. In this case no shortcode or
# codefence be involved an' th' library be not boarded by default. In this case
# ye can set `disableMermaid=false` 'n yer frontmatter t' force th' library t'
# be boarded.
# If not set, th' set value o' yer site's hugo.toml be used.
disableMermaid = true

# URL fer external Merrrmaid library.
# Default: not set
# Specifies th' remote locat'n o' th' Merrrmaid library. By default th' shipped
# version will be used.
# If not set, th' set value o' yer site's hugo.toml be used.
customMermaidURL = "" # "https://unpkg.com/mermaid/dist/mermaid.min.js"

#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
# OpenApi
# These opt'ns configure how OpenAPI specificat'ns be displayed.

# Only board OpenAPI if needed.
# Default: true
# If a OpenAPI shortcode be found, th' opt'n will be ignored an'
# OpenAPI will be boarded regardlessly. Th' opt'n be still useful 'n case ye
# be us'n script'n t' set up yer graph. In this case no shortcode or
# codefence be involved an' th' library be not boarded by default. In this case
# ye can set `disableOpenapi=false` 'n yer frontmatter t' force th' library t'
# be boarded.
# If not set, th' set value o' yer site's hugo.toml be used.
disableOpenapi = true

# URL fer external OpenAPI library.
# Default: not set
# Specifies th' remote locat'n o' th' OpenAPI library. By default th' shipped
# version will be used.
# If not set, th' set value o' yer site's hugo.toml be used.
customOpenapiURL = "" # "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"

# What t' do when a local OpenAPI spec link be not resolved.
# Default: ""
# Ye can control what should happen if a local OpenAPI spec link can not be resolved
# t' a resource. If not set, th' unresolved link be written as given into th' result'n
# output. If set t' `warning` th' same happens an' an additional warning be
# printed. If set t' `error` an error message be printed an' th' build be
# aborted.
# Please note that this can not resolve files inside o' yer `static` directory.
# If not set, th' set value o' yer site's hugo.toml be used.
openapi.errorlevel = ""
+++

Some Detailed Examples

Add Ay'con t' a Menu Entry

In th' plank frontmatter, add a menuPre param t' insert any HTML code before th' menu label. Th' example below uses th' GitHub ay'con.

+++
menuPre = "<i class='fab fa-github'></i> "
title = 'GitHub repo'
+++
---
menuPre: '<i class=''fab fa-github''></i> '
title: GitHub repo
---
{
   "menuPre": "\u003ci class='fab fa-github'\u003e\u003c/i\u003e ",
   "title": "GitHub repo"
}

Title wit' icon Title wit' icon

Order'n Sibl'n Menu/Page Entries

Cap'n Hugo provides a flex'ble way t' handle order fer yer planks.

Th' simplest way be t' set weight parameter t' a number.

+++
title = 'My page'
weight = 5
+++
---
title: My plank
weight: 5
---
{
   "title": "My page",
   "weight": 5
}

Us'n a Custom Title fer Menu Entries

By default, th' Relearrrn theme will use a page’s title attribute fer th' menu item.

But a page’s title has t' be descriptive on its own while th' menu be a hierarchy. Cap'n Hugo adds th' linkTitle parameter fer that purpose:

For example (for a plank named content/install/linux.md):

+++
linkTitle = 'Linux'
title = 'Install on Linux'
+++
---
linkTitle: Linux
title: Install on Linux
---
{
   "linkTitle": "Linux",
   "title": "Install on Linux"
}

Override Expand State Rules fer Menu Entries

Ye can change how th' theme expands menu entries on th' side o' th' rrrambl'n wit' th' alwaysopen sett'n on a per plank basis. If alwaysopen=false fer any given entry, its children will not be shown 'n th' menu as long as it be not necessary fer th' sake o' navigat'n.

Th' theme generates th' menu based on th' follow'n rules:

  • all parent entries o' th' active plank includ'n their sibl'ns be shown regardless o' any sett'ns
  • immediate children entries o' th' active plank be shown regardless o' any sett'ns
  • if not overridden, all other first level entries behave like they would have been given alwaysopen=false
  • if not overridden, all other entries o' levels besides th' first behave like they would have been given alwaysopen=true
  • all vis'ble entries show their immediate children entries if alwaysopen=true; this proceeds recursively
  • all remain'n entries be not shown

Ye can see this feature 'n act'n on th' example plank fer children shortcode an' its children planks.

Dis'ble Sect'n Planks

Ye may want t' structure yer planks 'n a hierarchical way but don’t want t' generate planks fer those sections? Th' theme got ye covered.

T' stay wit' th' initial example: Suppose ye want level-one appear 'n th' sidebar but don’t want t' generate a plank fer it. So th' entry 'n th' sidebar should not be click'ble but should show an expander.

For this, open content/level-one/_index.md an' add th' follow'n frontmatter

+++
collapsibleMenu = true

[_build]
  render = 'never'
+++
---
_build:
  render: never
collapsibleMenu: true
---
{
   "_build": {
      "render": "never"
   },
   "collapsibleMenu": true
}