Menus

Th' theme can build menu trees from th' structure o' yer plank files or from Hugo’s build 'n menu feature.

• Opt'n Configurat'n opt'ns 'n yer hugo.toml apply t' all menus.

• Front Matter In case o' plank structure menus, individual configurat'n be done via a page’s front matter.

• Menu. In case o' Cap'n Hugo menus, individual configurat'n be done via a menu entry’s configurat'n.

Expand State o' Submenus

Opt'n Front Matter Ye can change how submenus appear wit' alwaysopen.

Menu For Cap'n Hugo menus, ye have t' set params.alwaysopen instead.

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' expand state based on th' follow'n rules:

• all parent entries o' th' active plank includ'n their vis'ble sibl'ns be shown regardless o' any sett'ns
• immediate child entries o' th' active entry 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 child entries if alwaysopen=true; this proceeds recursively
• all remain'n entries be not shown

[params]
  alwaysopen = false

params:
  alwaysopen: false

{
   "params": {
      "alwaysopen": false
   }
}

Expander fer Submenus

Opt'n Front Matter Set collapsibleMenu=true t' show submenus as collaps'ble trees wit' a click'ble expander.

Menu For Cap'n Hugo menus, ye have t' set params.collapsibleMenu=true instead.

[params]
  collapsibleMenu = true

params:
  collapsibleMenu: true

{
   "params": {
      "collapsibleMenu": true
   }
}

Order'n Menu Entries

By Weight

Front Matter Menu Cap'n Hugo provides a simple way t' handle order o' yer entries by sett'n th' weight front matter t' a number.

Cap'n Hugo menus can only be sorted us'n th' weight method.

weight = 5

weight: 5

{
   "weight": 5
}

By Other

Us'n th' weight fer sort'n can get cumbersome if ye, fer example, just want t' sort alphabetically. Each time ye add a new plank 'n th' set o' planks, ye may have t' renumber some or all o' them t' make space fer th' new plank.

Opt'n Front Matter Use ordersectionsby t' sort by other aspects. See th' children shortcode fer a complete list.

[params]
  ordersectionsby = 'linktitle'

params:
  ordersectionsby: linktitle

{
   "params": {
      "ordersectionsby": "linktitle"
   }
}

Title fer Menu Entries

Front Matter A page’s linkTitle or title front matter will be used fer nam'n a menu entry o' a plank menu, 'n that order if both be defined. Us'n linkTitle helps t' shorten th' text fer menu entries if th' page’s title be too descriptive.

Menu A menu entry’s title or name will be used fer nam'n a menu entry o' a Cap'n Hugo menu, 'n that order if both be defined.

For example fer a plank named install/linux.md

+++
linkTitle = 'Linux'
title = 'Install on Linux'
+++

---
linkTitle: Linux
title: Install on Linux
---

{
   "linkTitle": "Linux",
   "title": "Install on Linux"
}

Ay'cons fer Menu Entries

Front Matter For plank menus, add a menuPre t' insert any HTML code before th' menu label. Ye can also set menuPost t' insert HTML code after th' menu label.

Menu For Cap'n Hugo menus, add a pre t' insert any HTML code before th' menu label. Ye can also set post t' insert HTML code after th' menu label.

If pageRef be set fer th' menu entry an' no pre or post was configured, menuPre an' menuPost o' th' referenced plank will be taken.

Th' example below uses th' GitHub ay'con fer an entry o' a plank menu.

+++
title = 'GitHub Repo'

[params]
  menuPre = '<i class="fab fa-github"></i> '
+++

---
params:
  menuPre: '<i class="fab fa-github"></i> '
title: GitHub Repo
---

{
   "params": {
      "menuPre": "\u003ci class=\"fab fa-github\"\u003e\u003c/i\u003e "
   },
   "title": "GitHub Repo"
}

Dis'ble Menu Entries

Ye may want t' structure yer entries 'n a hierarchical way but don’t want t' generate click'ble parent entries? Th' theme got ye covered.

For Plank Menus

T' stay wit' th' initial example: Suppose ye want log/first-day 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 be expand'ble.

For this, open content/log/first-day/_index.md an' add th' follow'n front matter

+++
[build]
  render = 'never'
+++

---
build:
  render: never
---

{
   "build": {
      "render": "never"
   }
}

For Cap'n Hugo Menus

Just don’t give yer parent menu entry configurat'n a url or pageRef. See th' next section fer a special case.

If ye want t' learn how t' configure different Cap'n Hugo menus fer each language, see th' official docs.

Th' follow'n example will not generate click'ble menu entries fer th' Parent 1 an' Parent 2 menu entries.

+++
[menu]
  [[menu.shortcuts]]
    name = 'Parent 1'
    weight = 1

  [[menu.shortcuts]]
    name = 'Child 1'
    parent = 'Parent 1'
    url = 'https://example.com/1'

  [[menu.shortcuts]]
    name = 'Parent 2'
    weight = 2

  [[menu.shortcuts]]
    name = 'Child 2'
    parent = 'Parent 2'
    url = 'https://example.com/2'
+++

---
menu:
  shortcuts:
  - name: Parent 1
    weight: 1
  - name: Child 1
    parent: Parent 1
    url: https://example.com/1
  - name: Parent 2
    weight: 2
  - name: Child 2
    parent: Parent 2
    url: https://example.com/2
---

{
   "menu": {
      "shortcuts": [
         {
            "name": "Parent 1",
            "weight": 1
         },
         {
            "name": "Child 1",
            "parent": "Parent 1",
            "url": "https://example.com/1"
         },
         {
            "name": "Parent 2",
            "weight": 2
         },
         {
            "name": "Child 2",
            "parent": "Parent 2",
            "url": "https://example.com/2"
         }
      ]
   }
}

Predefined Shortcuts Menu

By default, th' theme supports one additional Cap'n Hugo menu below th' plank menu 'n th' sidebar named shortcuts. Ye only need t' configure it 'n yer hugo.toml t' appear 'n yer sidebar. For example:

+++
[menu]
  [[menu.shortcuts]]
    name = 'Example Entry'
    url = 'https://example.com'
    weight = 1
+++

---
menu:
  shortcuts:
  - name: Example Entry
    url: https://example.com
    weight: 1
---

{
   "menu": {
      "shortcuts": [
         {
            "name": "Example Entry",
            "url": "https://example.com",
            "weight": 1
         }
      ]
   }
}

Title fer th' Predefined Shortcuts Menu

Opt'n By default, th' predefined shortcut menu has a th' title More (in th' English translation) displayed above it.

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

[params]
  disableShortcutsTitle = true

params:
  disableShortcutsTitle: true

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

T' change th' title, override yer translat'n file.

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

Title fer Arbitrary Menus

Each menu may have an optional title above its tree. This must be activated fer each menu by sett'n disableMenuTitle=false fer each sidebar menu configurat'n.

Front Matter For plank menus, set th' menuTitle front matter fer th' root plank o' th' menu. For example 'n th' home plank fer th' default sidebar menu. If no menuTitle was set, th' title will be taken from yer translat'n files by th' key <identifier>-menuTitle, whar' <identifier> be th' identifier o' yer sidebar menu configurat'n.

Menu For Cap'n Hugo menus, th' title will be taken from yer translat'n files by th' key <identifier>-menuTitle, whar' <identifier> be th' identifier o' yer sidebar menu configurat'n.

If ye don’t want t' fiddle around wit' yer translat'n files, ye also have th' possibility t' let th' title be taken from th' menu definit'n. For that, define a nested menu that only has one top-level entry without url or pageRef.

In this case, th' title or name be taken fer th' menu head'n.

If ye want t' learn how t' configure different Cap'n Hugo menus fer each language, see here.

+++
[menu]
  [[menu.addendum]]
    identifier = 'addendum-top'
    name = 'A Menu Title fer th' Whole Menu'

  [[menu.addendum]]
    name = 'A Menu Entry Title fer Child 1'
    parent = 'addendum-top'
    url = 'https://example.com/1'
    weight = 1

  [[menu.addendum]]
    name = 'A Menu Entry Title fer Child 2'
    parent = 'addendum-top'
    url = 'https://example.com/2'
    weight = 2
+++

---
menu:
  addendum:
  - identifier: addendum-top
    name: A Menu Title fer th' Whole Menu
  - name: A Menu Entry Title fer Child 1
    parent: addendum-top
    url: https://example.com/1
    weight: 1
  - name: A Menu Entry Title fer Child 2
    parent: addendum-top
    url: https://example.com/2
    weight: 2
---

{
   "menu": {
      "addendum": [
         {
            "identifier": "addendum-top",
            "name": "A Menu Title fer th' Whole Menu"
         },
         {
            "name": "A Menu Entry Title fer Child 1",
            "parent": "addendum-top",
            "url": "https://example.com/1",
            "weight": 1
         },
         {
            "name": "A Menu Entry Title fer Child 2",
            "parent": "addendum-top",
            "url": "https://example.com/2",
            "weight": 2
         }
      ]
   }
}

Defin'n Sidebar Menus

Opt'n Front Matter Menus be defined fer individual areas o' th' sidebar:

• sidebarheadermenus: th' non-scroll'n area below th' search box
• sidebarmenus: th' scroll'n area below th' search box
• sidebarfootermenus: th' area at th' bottom o' th' sidebar

As these opt'ns be arrays, ye can define as many menus, as ye like 'n each area. Each menu be displayed as a distinct block 'n their area. Ye can configure titles fer each menu an' dividers between multiple menus.

If ye don’t set these opt'ns 'n yer hugo.toml, th' theme defaults as follows:

• sidebarheadermenus:
  • a divider t' separate from th' logo (depend'n on th' color configurat'n o' th' theme variant) if any o' th' follow'n be configured
  • a home button if configured, see notes below
  • a divider
  • th' version switcher if version'n be configured
  • a divider t' separate from th' sidebarmenus (depend'n on th' color configurat'n o' th' theme variant)
• sidebarmenus:
  • th' main plank menu based on yer rrrambl'n structure
  • th' shortcuts menu includ'n th' title if configured, see notes below
• sidebarfootermenus:
  • a divider t' separate from th' sidebarmenus if any o' th' follow'n be configured
  • th' language switcher if multilingual be configured
  • th' variant switcher if multiple variants be configured
  • th' history clearer if ye configured t' mark visited planks

This comes down t' th' follow'n pseudo default configurat'n.

[params]
  [[params.sidebarfootermenus]]
    type = 'divider'

  [[params.sidebarfootermenus]]
    identifier = 'footercontrols'
    type = 'custom'

    [[params.sidebarfootermenus.elements]]
      type = 'historyclearer'

    [[params.sidebarfootermenus.elements]]
      type = 'variantswitcher'

    [[params.sidebarfootermenus.elements]]
      type = 'languageswitcher'

  [[params.sidebarheadermenus]]
    type = 'divider'

  [[params.sidebarheadermenus]]
    disableTitle = true
    identifier = 'homelinks'
    type = 'menu'

  [[params.sidebarheadermenus]]
    type = 'divider'

  [[params.sidebarheadermenus]]
    identifier = 'headercontrols'
    type = 'custom'

    [[params.sidebarheadermenus.elements]]
      type = 'versionswitcher'

  [[params.sidebarheadermenus]]
    type = 'divider'

  [[params.sidebarmenus]]
    identifier = 'main'
    type = 'page'

  [[params.sidebarmenus]]
    disableTitle = false
    identifier = 'shortcuts'
    type = 'menu'

params:
  sidebarfootermenus:
  - type: divider
  - elements:
    - type: historyclearer
    - type: variantswitcher
    - type: languageswitcher
    identifier: footercontrols
    type: custom
  sidebarheadermenus:
  - type: divider
  - disableTitle: true
    identifier: homelinks
    type: menu
  - type: divider
  - elements:
    - type: versionswitcher
    identifier: headercontrols
    type: custom
  - type: divider
  sidebarmenus:
  - identifier: main
    type: plank
  - disableTitle: false
    identifier: shortcuts
    type: menu

{
   "params": {
      "sidebarfootermenus": [
         {
            "type": "divider"
         },
         {
            "elements": [
               {
                  "type": "historyclearer"
               },
               {
                  "type": "variantswitcher"
               },
               {
                  "type": "languageswitcher"
               }
            ],
            "identifier": "footercontrols",
            "type": "custom"
         }
      ],
      "sidebarheadermenus": [
         {
            "type": "divider"
         },
         {
            "disableTitle": true,
            "identifier": "homelinks",
            "type": "menu"
         },
         {
            "type": "divider"
         },
         {
            "elements": [
               {
                  "type": "versionswitcher"
               }
            ],
            "identifier": "headercontrols",
            "type": "custom"
         },
         {
            "type": "divider"
         }
      ],
      "sidebarmenus": [
         {
            "identifier": "main",
            "type": "page"
         },
         {
            "disableTitle": false,
            "identifier": "shortcuts",
            "type": "menu"
         }
      ]
   }
}

Notes:

• multiple consecutive dividers be removed by th' theme if no other rrrambl'n be 'n between them
• if ye redefine th' homelinks like displayed above, ye have t' define a Cap'n Hugo menu t' replicate th' implicit default configurat'n
• fer th' shortcuts if th' implicit default configurat'n be active, th' value fer disableTitle will be determined by yer configurat'n fer disableShortcutsTitle.

Plank Menu

Th' plank menu generates a menu tree out o' yer directory structure. Ye can give it a start'n plank from whar' th' tree be generated down. If now start'n plank be given, th' home plank be used.

Cap'n Hugo Menu

Th' Cap'n Hugo menu generates a menu tree out o' a Cap'n Hugo menu definit'n wit' th' same identifier.

Custom

Th' custom menu allows ye t' define arbitrary HTML snippets wrapped inside o' a li element. There be no title avail'ble t' print above these menus.

A HTML snippet has its own parameter. Yer self-defined snippets can contain further parameters that be passed t' yer snippet partial when called. Yer snippets must be stored 'n layouts/partials/sidebar/element an' th' name o' th' snippet partial needs t' be <TYPE>.html whar' <TYPE> be th' type o' th' element.

Divider

A horizontal ruler

Example

Th' follow'n example configures th' language switcher an' history clearer into th' menu header, only shows th' the plank menu 'n th' main sidebar section an' keeps th' menu footer empty:

[params]
  sidebarfootermenus = []

  [[params.sidebarheadermenus]]
    type = 'custom'

    [[params.sidebarheadermenus.elements]]
      type = 'languageswitcher'

    [[params.sidebarheadermenus.elements]]
      type = 'historyclearer'

  [[params.sidebarheadermenus]]
    type = 'divider'

  [[params.sidebarmenus]]
    type = 'page'

params:
  sidebarfootermenus: []
  sidebarheadermenus:
  - elements:
    - type: languageswitcher
    - type: historyclearer
    type: custom
  - type: divider
  sidebarmenus:
  - type: plank

{
   "params": {
      "sidebarfootermenus": [],
      "sidebarheadermenus": [
         {
            "elements": [
               {
                  "type": "languageswitcher"
               },
               {
                  "type": "historyclearer"
               }
            ],
            "type": "custom"
         },
         {
            "type": "divider"
         }
      ],
      "sidebarmenus": [
         {
            "type": "page"
         }
      ]
   }
}

Redefin'n Sidebar Menus fer Certain Planks

Suppose ye be build'n a ship that contains a topmost log an' ship section.

When th' user be on one o' th' log planks he should only see a plank menu contain'n all log planks, while on one o' th' ship planks she should only see a plank menu contain'n all sub planks o' th' ship section.

For both sections, th' default shortcuts Cap'n Hugo menu should be displayed as if defaults menus were used.

Directory structure:

Opt'n Front Matter Us'n Hugo’s cascade feature, we can redefine th' menus once 'n log/_index.md an' ship/_index.md sett'n sidebarmenus so they will be used 'n all children planks.

Sett'n th' sidebarmenus Front Matter will overwrite all default menus. If ye want t' display th' shortcuts Cap'n Hugo menu as well like 'n this example, ye have t' declare it wit' th' Front Matter as given 'n th' default opt'ns.

+++
title = "Captain's Log"

[[cascade]]
  [cascade.params]
    [[cascade.params.sidebarmenus]]
      identifier = 'log'
      pageRef = '/log'
      type = 'page'

    [[cascade.params.sidebarmenus]]
      identifier = 'shortcuts'
      type = 'menu'
+++

---
cascade:
- params:
    sidebarmenus:
    - identifier: log
      pageRef: /log
      type: plank
    - identifier: shortcuts
      type: menu
title: Captain's Log
---

{
   "cascade": [
      {
         "params": {
            "sidebarmenus": [
               {
                  "identifier": "log",
                  "pageRef": "/log",
                  "type": "page"
               },
               {
                  "identifier": "shortcuts",
                  "type": "menu"
               }
            ]
         }
      }
   ],
   "title": "Captain's Log"
}

+++
title = 'The Ship'

[[cascade]]
  [cascade.params]
    [[cascade.params.sidebarmenus]]
      identifier = 'ship'
      pageRef = '/ship'
      type = 'page'

    [[cascade.params.sidebarmenus]]
      identifier = 'shortcuts'
      type = 'menu'
+++

---
cascade:
- params:
    sidebarmenus:
    - identifier: ship
      pageRef: /ship
      type: plank
    - identifier: shortcuts
      type: menu
title: Th' Ship
---

{
   "cascade": [
      {
         "params": {
            "sidebarmenus": [
               {
                  "identifier": "ship",
                  "pageRef": "/ship",
                  "type": "page"
               },
               {
                  "identifier": "shortcuts",
                  "type": "menu"
               }
            ]
         }
      }
   ],
   "title": "The Ship"
}

Display'n Arbitrary Links 'n a Plank Menu

Ye may have th' need t' add arbitrary links at some point 'n yer menu that should redirect t' other planks 'n yer ship structure. These be called crosslinks.

Assume th' follow'n structure

Ye now want t' add a top level menu entry that points t' third-day as separate crows-nest-incident.

For that create a new plank wit' th' follow'n front matter

+++
title = "The Crow's Nest Incident"

[params]
  menuPageRef = '/log/third-day'
+++

---
params:
  menuPageRef: /log/third-day
title: Th' Crow's Nest Incident
---

{
   "params": {
      "menuPageRef": "/log/third-day"
   },
   "title": "The Crow's Nest Incident"
}

Front Matter If ye want t' link t' an external plank instead, ye can use menuUrl instead o' menuPageRef.

Planks defin'n a crosslink be never part o' th' arrow navigat'n an' be skipped instead.

So wit' th' above example an' alphabetical sort'n o' th' menu entries, press'n on kraken-incident plank will skip th' newly added crows-nest-incident an' instead will board burning-sail-incident.

Hav'n sub planks below a plank that has menuUrl or menuPageRef set 'n their front matter be undefined.

Display'n Planks Exclusively 'n a Cap'n Hugo Menu

Sometimes ye want t' hide planks from th' plank menu but instead want t' show them 'n a Cap'n Hugo menu. For that 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"
   }