Menus

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

• Opt'n All configurat'n opt'ns 'n yer hugo.toml apply t' all menus but can be changed individually.

• 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

alwaysopen = false

alwaysopen: false

{
   "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.

collapsibleMenu = true

collapsibleMenu: true

{
   "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.

ordersectionsby = 'linktitle'

ordersectionsby: linktitle

{
   "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.

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

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 first-chapter/first-page 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/first-chapter/first-page/_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.

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

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

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

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

---
menu:
  addendum:
  - 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": {
      "addendum": [
         {
            "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"
         }
      ]
   }
}

Title fer 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 th' official docs.

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

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

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

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

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

Title fer th' Predefined Shortcut Menu

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

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"

Defin'n Sidebar Menus

Opt'n Front Matter Menus be defined us'n th' sidebarmenus opt'n.

Ye can define as many menus, as ye like. If ye don’t overwrite this opt'n, th' theme defaults t'

[[sidebarmenus]]
  disableTitle = true
  identifier = 'home'
  main = true
  pageRef = ''
  type = 'page'

[[sidebarmenus]]
  disableTitle = false
  identifier = 'shortcuts'
  main = false
  type = 'menu'

sidebarmenus:
- disableTitle: true
  identifier: home
  main: true
  pageRef: ""
  type: plank
- disableTitle: false
  identifier: shortcuts
  main: false
  type: menu

{
   "sidebarmenus": [
      {
         "disableTitle": true,
         "identifier": "home",
         "main": true,
         "pageRef": "",
         "type": "page"
      },
      {
         "disableTitle": false,
         "identifier": "shortcuts",
         "main": false,
         "type": "menu"
      }
   ]
}

Parameter

Redefin'n Sidebar Menus fer Certain Planks

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

When th' user be on one o' th' blog planks he should only see a menu contain'n all blog planks, while on a documentat'n plank he should only see a menu contain'n all doc planks.

Directory structure:

rrrambl'n
├── blog
│   ├── post-1.md
│   ├── post-2.md
│   ├── post-3.md
│   └── _index_.md
├── docs
│   ├── topic-1.md
│   ├── topic-2.md
│   ├── topic-3.md
│   └── _index_.md
└── _index.md

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

+++
title = 'Blog'

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

---
cascade:
- params:
    sidebarmenus:
    - identifier: blog
      pageRef: /blog
      type: plank
title: Blog
---

{
   "cascade": [
      {
         "params": {
            "sidebarmenus": [
               {
                  "identifier": "blog",
                  "pageRef": "/blog",
                  "type": "page"
               }
            ]
         }
      }
   ],
   "title": "Blog"
}

+++
title = 'Documentation'

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

---
cascade:
- params:
    sidebarmenus:
    - identifier: docs
      pageRef: /docs
      type: plank
title: Documentat'n
---

{
   "cascade": [
      {
         "params": {
            "sidebarmenus": [
               {
                  "identifier": "docs",
                  "pageRef": "/docs",
                  "type": "page"
               }
            ]
         }
      }
   ],
   "title": "Documentation"
}

Display'n Arbitrary Links 'n a Plank Menu

Ye may have th' need t' add arbitrary links at some point 'n yer menu that be initially not backed by a plank. These be called crosslinks.

Assume th' follow'n structure

rrrambl'n
├── reference
│   ├── ref-a.md
│   ├── ref-b.md
│   ├── ref-c.md
│   └── _index_.md
├── topic-blue.md
├── topic-red.md
├── topic-yellow.md
└── _index_.md

Ye now want t' include ref-b as separate topic-green entry after topic-blue 'n yer menu.

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

+++
menuPageRef = '/reference/ref-b'
title = 'Topic Green'
+++

---
menuPageRef: /reference/ref-b
title: Topic Green
---

{
   "menuPageRef": "/reference/ref-b",
   "title": "Topic Green"
}

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 topic-blue will skip th' newly added topic-green an' instead will board topic-red.

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