Width

The theme adjusts the menu width based on browser size.

If you want to change the chosen default width, you can add CSS variables to layouts/partials/custom-header.html.

Changing Menu Width

The menu width changes for different screen sizes:

You can change the menu width but not the screen width breakpoints.

To adjust the menu width, use these CSS variables. Note that --MENU-S-width is for the mobile menu flyout on small screens.

<style>
:root {
    --MENU-S-width: 14.375rem;
    --MENU-M-width: 14.375rem;
    --MENU-L-width: 18.75rem;
}
</style>

Header & Footer

Title & Logo

See the title & logo configuration on how to set a title and a logo.

Home Button Configuration

By default, the theme displays a home button between search form and navigation menu. The Home button serves as an alternative to clicking the logo.

Option To hide the Home button on the left menu, set disableLandingPageButton to true.

params:
  disableLandingPageButton: true

[params]
  disableLandingPageButton = true

{
   "params": {
      "disableLandingPageButton": true
   }
}

Option To change its icon or text, configure the landingPageName for your defined languages.

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]
  [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": "\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 option isn’t set for a specific language, it will use these default values

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

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

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

For a free configuration of the header menus, see configuration of the sidebar menus.

History

Option Set showVisitedLinks to true to see checkmarks next to visited pages in the main menu. This also adds a history clearer button at the bottom of the menu to remove all checkmarks.

If you want to have more control, where the history clearer is positioned or you want to configure a different icon, see the chapter on sidebar configuration.

Note that checkmarks will disappear if you rebuild your site, as the page IDs may change.

params:
  showVisitedLinks: true

[params]
  showVisitedLinks = true

{
   "params": {
      "showVisitedLinks": true
   }
}

Footer

To change the menu footer, edit the layouts/partials/menu-footer.html file. Check out the Partials section for more ways to customize your site.

Search

Configure Search

The theme offers three levels of search through the menu’s search form:

1. In-page search: Highlights search terms on the current page
2. Search popup: Opens a popup with results from other pages
3. Dedicated search page: Accessible by clicking the magnifier glass or pressing ENTER

Each level requires the previous one to be enabled. If no search is configured, the search form won’t appear.

Option All levels are enabled by default. Disable them in your project configuration:

• In-page search: set search.disable to true
• Search popup: set search.index.disable to true
• Dedicated search page: set search.page.disable to true

params:
  search:
    disable: true
    index:
      disable: true
    page:
      disable: true

[params]
  [params.search]
    disable = true

    [params.search.index]
      disable = true

    [params.search.page]
      disable = true

{
   "params": {
      "search": {
         "disable": true,
         "index": {
            "disable": true
         },
         "page": {
            "disable": true
         }
      }
   }
}

Search URLs

Option Default URLs can be changed with the following parameter

• Search popup: searchindex.js set by search.index.URL
• Dedicated search page: search/index.html set by search.page.URL

params:
  search:
    index:
      URL: omnisearchindex.js
    page:
      URL: omnisearch

[params]
  [params.search]
    [params.search.index]
      URL = 'omnisearchindex.js'

    [params.search.page]
      URL = 'omnisearch'

{
   "params": {
      "search": {
         "index": {
            "URL": "omnisearchindex.js"
         },
         "page": {
            "URL": "omnisearch"
         }
      }
   }
}

Search Adapter / Engine

Option The theme supports different search engines through adapters. Each different adapter may have its own set of configuration.

By default, it uses the Lunr search engine.

params:
  search:
    adapter:
      identifier: lunr

[params]
  [params.search]
    [params.search.adapter]
      identifier = 'lunr'

{
   "params": {
      "search": {
         "adapter": {
            "identifier": "lunr"
         }
      }
   }
}

Lunr

lunr is the default search adapter.

Supported Languages

Lunr doesn’t support all languages of the theme. Content of an unsupported language is dropped from the search index, so searching it will not return any results. The theme warns you about this during your Hugo build. Currently unsupported are

• Czech
• Indonesian
• Persian
• Swahili
• Ukrainian

Mixed Language Support

Option In case your page’s content contains text in multiple languages (for example, you are writing a Piratish documentation for your English API), you can set those languages in search.adapter.params.additionalContentLanguage to broaden the search.

params:
  search:
    adapter:
      params:
        additionalContentLanguage:
        - en

[params]
  [params.search]
    [params.search.adapter]
      [params.search.adapter.params]
        additionalContentLanguage = ['en']

{
   "params": {
      "search": {
         "adapter": {
            "params": {
               "additionalContentLanguage": [
                  "en"
               ]
            }
         }
      }
   }
}

You can add multiple languages to this array.

Experimental Adapters

The theme also ships with the additional experimental orama and orama-esm (not usable for headless server deployments) adapters.

Publishing the Search Index as JSON

Option The search popup loads its index as a script, so your site’s search keeps working when it is opened from the file system. If other tools want to read your index, like an MCP server, set search.index.json to true to additionally write the same data as a plain JSON file.

params:
  search:
    index:
      json: true

[params]
  [params.search]
    [params.search.index]
      json = true

{
   "params": {
      "search": {
         "index": {
            "json": true
         }
      }
   }
}

The JSON file is written next to the search index with the extension .json, for example searchindex.en.json. Its content is minified like the theme’s other assets, depending on the minify option. Its URL stays the same regardless of its content or minification, so other tools can rely on it.

Customizing the Search Index Generation

Option You can customize how the search index is generated by specifying a different template:

params:
  search:
    index:
      template: /custom_searchindex.json

[params]
  [params.search]
    [params.search.index]
      template = '/custom_searchindex.json'

{
   "params": {
      "search": {
         "index": {
            "template": "/custom_searchindex.json"
         }
      }
   }
}

By default, the theme uses /_relearn_searchindex.json to generate the search index. When you specify a custom value for search.index.template, the theme will look for the template file in your site’s assets directory.

For example, if you set search.index.template to /custom_searchindex.json, you would need to create a file at assets/custom_searchindex.json in your site to define the custom index generation logic.

The template must return the index as JSON. The theme uses it for the search popup as well as for the JSON file, so all search adapters get the same data.

This advanced option is useful if you need to modify how content is indexed or change the structure of the search index to work with custom search implementations.

Customizing the Search Page Layout

Option You can customize the appearance of the dedicated search page by changing its content view:

params:
  search:
    page:
      type: custom_search_layout

[params]
  [params.search]
    [params.search.page]
      type = 'custom_search_layout'

{
   "params": {
      "search": {
         "page": {
            "type": "custom_search_layout"
         }
      }
   }
}

By default, the theme uses _relearn_searchpage as the search content view. When you set search.page.type to a custom value [YOUR-VIEWNAME], Hugo will look for a template file at layouts/[YOUR-VIEWNAME]/article.html.

For example, if you set search.page.type to custom_search_layout, you would need to create a file at layouts/custom_search_layout/article.html in your site to define the custom layout.

This allows you to maintain the search functionality while adapting its appearance to match your specific design requirements.

Printing the Search Results

If your home page has print support activated, your readers can print their search results as well. The search page then shows the print button, and the printed page lists the results for the current search term without the search form.

Option The dedicated search page is not part of your content, so the outputs of your project configuration or of a front matter don’t apply to it. If you want to decide independently of your home page, set its output formats with search.page.outputs.

To never offer printing the search results:

params:
  search:
    page:
      outputs:
      - html

[params]
  [params.search]
    [params.search.page]
      outputs = ['html']

{
   "params": {
      "search": {
         "page": {
            "outputs": [
               "html"
            ]
         }
      }
   }
}

To always offer it:

params:
  search:
    page:
      outputs:
      - html
      - print

[params]
  [params.search]
    [params.search.page]
      outputs = ['html', 'print']

{
   "params": {
      "search": {
         "page": {
            "outputs": [
               "html",
               "print"
            ]
         }
      }
   }
}

Migration from Relearn 7

In previous versions of the theme, search configuration used flat parameters. The current version uses a more structured approach with a search namespace.

If you’re updating from an older version, here’s how to migrate your search configuration:

Migration Table

Menus

The theme can build menu trees from the structure of your page files or from Hugo’s build in menu feature.

• Option Configuration options in your project configuration apply to all menus.

• Front Matter In case of page structure menus, individual configuration is done via a page’s front matter.

• Menu. In case of Hugo menus, individual configuration is done via a menu entry’s configuration.

Expand State of Submenus

Option Front Matter You can change how submenus appear with alwaysopen.

Menu For Hugo menus, you have to set params.alwaysopen instead.

If alwaysopen is false for any given entry, its children will not be shown in the menu as long as it is not necessary for the sake of navigation.

The theme generates the expand state based on the following rules:

• all parent entries of the active page including their visible siblings are shown regardless of any settings
• immediate child entries of the active entry are shown regardless of any settings
• if not overridden, all other first level entries behave like they would have been given alwaysopen set to false
• if not overridden, all other entries of levels besides the first behave like they would have been given alwaysopen set to true
• all visible entries show their immediate child entries if alwaysopen is true; this proceeds recursively
• all remaining entries are not shown

params:
  alwaysopen: false

[params]
  alwaysopen = false

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

Expander for Submenus

Option Front Matter Set collapsibleMenu to true to show submenus as collapsible trees with a clickable expander.

Menu For Hugo menus, you have to set params.collapsibleMenu to true instead.

params:
  collapsibleMenu: true

[params]
  collapsibleMenu = true

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

Ordering Menu Entries

By Hugo’s Default Sort Order

Front Matter Menu Hugo provides a simple way to handle order of your entries taking into account the weight, date and linkTitle front matter .

Menu Hugo menus can only be sorted by weight.

weight: 5

weight = 5

{
   "weight": 5
}

By Other

Option Front Matter Use ordersectionsby to sort by other aspects if Hugo’s default sort order does not match your needs. It accepts weight, title, linktitle, lastmod, expirydate, publishdate, date, length or default (adhering to Hugo’s default sort order). Both title and linktitle sort by the title shown in the menu.

params:
  ordersectionsby: linktitle

[params]
  ordersectionsby = 'linktitle'

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

Title for Menu Entries

Front Matter A page’s linkTitle or title front matter will be used for naming a menu entry of a page menu, in that order if both are defined. Using linkTitle helps to shorten the text for menu entries if the page’s title is too descriptive.

Menu A menu entry’s title or name will be used for naming a menu entry of a Hugo menu, in that order if both are defined.

For example for a page named install/linux.md

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

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

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

Icons for Menu Entries

Front Matter For page menus, add a menuPre to insert any HTML code before the menu label. You can also set menuPost to insert HTML code after the menu label.

Menu For Hugo menus, add a pre to insert any HTML code before the menu label. You can also set post to insert HTML code after the menu label.

If pageRef is set for the menu entry and no pre or post was configured, menuPre and menuPost of the referenced page will be taken.

The example below uses the GitHub icon for an entry of a page menu.

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

+++
title = 'GitHub Repo'

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

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

Disable Menu Entries

You may want to structure your entries in a hierarchical way but don’t want to generate clickable parent entries? The theme got you covered.

For Page Menus

To stay with the initial example: Suppose you want log/first-day appear in the sidebar but don’t want to generate a page for it. So the entry in the sidebar should not be clickable but should be expandable.

For this, open content/log/first-day/_index.md and add the following front matter

---
build:
  render: never
---

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

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

For Hugo Menus

Just don’t give your parent menu entry configuration a url or pageRef. See the next section for a special case.

If you want to learn how to configure different Hugo menus for each language, see the official docs.

The following example will not generate clickable menu entries for the Parent 1 and Parent 2 menu entries.

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

Page Trees in Hugo Menus

Menu An entry of a Hugo menu usually ends where your menu definition ends. If you set params.type to page for an entry with a pageRef, the entry is continued by the tree of the page it links to, the same way a page menu starting at that page would show it.

This saves you from repeating your page structure in your menu definition. The entry keeps its own title, pre and post.

If the entry links to a taxonomy page, its terms are shown below it. A term ends the tree, as the pages it lists have their place elsewhere in your menus.

The following example shows all tags of your site below the Tags entry.

menu:
  shortcuts:
  - name: Tags
    pageRef: /tags
    params:
      type: page

[menu]
  [[menu.shortcuts]]
    name = 'Tags'
    pageRef = '/tags'

    [menu.shortcuts.params]
      type = 'page'

{
   "menu": {
      "shortcuts": [
         {
            "name": "Tags",
            "pageRef": "/tags",
            "params": {
               "type": "page"
            }
         }
      ]
   }
}

Predefined Shortcuts Menu

By default, the theme supports one additional Hugo menu below the page menu in the sidebar named shortcuts. You only need to configure it in your project configuration to appear in your sidebar. For example:

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

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

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

Title for the Predefined Shortcuts Menu

Option By default, the predefined shortcut menu has a the title More (in the English translation) displayed above it.

You can disable this title by setting disableShortcutsTitle to true.

params:
  disableShortcutsTitle: true

[params]
  disableShortcutsTitle = true

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

To change the title, override your translation file.

shortcuts-menuTitle:
  other: Other Great Stuff

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

{
   "shortcuts-menuTitle": {
      "other": "Other Great Stuff"
   }
}

Title for Arbitrary Menus

Each menu may have an optional title above its tree. This must be activated for each menu by setting disableTitle to false for each sidebar menu configuration.

Front Matter For page menus, set the linkTitle front matter for the root page of the menu. For example in the home page for the default sidebar menu. If no linkTitle was set, the title will be taken from your translation files by the key <identifier>-menuTitle, where <identifier> is the identifier of your sidebar menu configuration.

Menu For Hugo menus, the title will be taken from your translation files by the key <identifier>-menuTitle, where <identifier> is the identifier of your sidebar menu configuration.

If you don’t want to fiddle around with your translation files, you also have the possibility to let the title be taken from the menu definition. For that, define a nested menu that only has one top-level entry without url or pageRef.

In this case, the title or name is taken for the menu heading.

If you want to learn how to configure different Hugo menus for each language, see here.

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

[menu]
  [[menu.addendum]]
    identifier = 'addendum-top'
    name = 'A Menu Title for the Whole Menu'

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

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

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

Defining Sidebar Menus

Option Front Matter Menus are defined for individual areas of the sidebar:

• sidebarheadermenus: the non-scrolling area below the search box
• sidebarmenus: the scrolling area below the search box
• sidebarfootermenus: the area at the bottom of the sidebar

As these options are arrays, you can define as many menus, as you like in each area. Each menu is displayed as a distinct block in their area. You can configure titles for each menu and dividers between multiple menus.

If you don’t set these options in your project configuration, the theme defaults as follows:

• sidebarheadermenus:
  • a divider to separate from the logo (depending on the color configuration of the theme variant) if any of the following is configured
  • a home button if configured, see notes below
  • a divider
  • the version switcher if versioning is configured
  • a divider to separate from the sidebarmenus (depending on the color configuration of the theme variant)
• sidebarmenus:
  • the main page menu based on your content structure
  • the shortcuts menu including the title if configured, see notes below
• sidebarfootermenus:
  • a divider to separate from the sidebarmenus if any of the following is configured
  • the language switcher if multilingual is configured
  • the variant switcher if multiple variants are configured
  • the history clearer if you configured to mark visited pages

This comes down to the following pseudo default configuration.

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

[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": "page"
         },
         {
            "disableTitle": false,
            "identifier": "shortcuts",
            "type": "menu"
         }
      ]
   }
}

Notes:

• multiple consecutive dividers are removed by the theme if no other content is in between them
• if you redefine the homelinks like displayed above, you have to define a Hugo menu to replicate the implicit default configuration
• for the shortcuts if the implicit default configuration is active, the value for disableTitle will be determined by your configuration for disableShortcutsTitle.

Page Menu

The page menu generates a menu tree out of your directory structure. You can give it a starting page from where the tree is generated down. If no starting page is given, the home page is used.

Hugo Menu

The Hugo menu generates a menu tree out of a Hugo menu definition with the same identifier.

Custom

The custom menu allows you to define arbitrary HTML snippets wrapped inside of a li element. There is no title available to print above these menus.

Custom Element

An HTML element snippet of a custom menu has its own parameter. Self-defined snippets have further parameters that are passed to your snippet partial when called. Your snippets must be stored in layouts/partials/sidebar/element and the name of the snippet partial needs to be <TYPE>.html where <TYPE> is the type of the element.

Divider

A horizontal ruler

Example

The following example

• configures the language switcher and history clearer into the menu header
• changes the icon of the language switcher to
• only shows the page menu in the main sidebar section
• keeps the menu footer empty

params:
  sidebarfootermenus: []
  sidebarheadermenus:
  - elements:
    - icon: globe
      type: languageswitcher
    - type: historyclearer
    type: custom
  - type: divider
  sidebarmenus:
  - type: page

[params]
  sidebarfootermenus = []

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

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

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

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

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

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

Redefining Sidebar Menus for Certain Pages

Suppose you are building a site that contains a topmost log and ship section.

When the user is on one of the log pages he should only see a page menu containing all log pages, while on one of the ship pages she should only see a page menu containing all sub pages of the ship section.

For both sections, the default shortcuts Hugo menu should be displayed as if defaults menus were used.

Directory structure:

Option Front Matter Using Hugo’s cascade feature, we can redefine the menus once in log/_index.md and ship/_index.md setting sidebarmenus so they will be used in all children pages.

Setting the sidebarmenus Front Matter will overwrite all default menus. If you want to display the shortcuts Hugo menu as well like in this example, you have to declare it with the Front Matter as given in the default options.

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

+++
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": "page"
               },
               {
                  "identifier": "shortcuts",
                  "type": "menu"
               }
            ]
         }
      }
   ],
   "title": "Captain's Log"
}

---
cascade:
- params:
    sidebarmenus:
    - identifier: ship
      pageRef: /ship
      type: page
    - identifier: shortcuts
      type: menu
title: The Ship
---

+++
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": "page"
               },
               {
                  "identifier": "shortcuts",
                  "type": "menu"
               }
            ]
         }
      }
   ],
   "title": "The Ship"
}

Displaying Arbitrary Links in a Page Menu

You may have the need to add arbitrary links at some point in your menu that should redirect to other pages in your site structure. These are called crosslinks.

Assume the following structure

You now want to add a top level menu entry that points to third-day as separate crows-nest-incident.

For that create a new page with the following front matter

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

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

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

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

Front Matter If you want to link to an external page instead, you can use menuUrl instead of menuPageRef.

Pages defining a crosslink are never part of the arrow navigation and are skipped instead.

So with the above example and alphabetical sorting of the menu entries, pressing on kraken-incident page will skip the newly added crows-nest-incident and instead will load burning-sail-incident.

Having sub pages below a page that has menuUrl or menuPageRef set in their front matter is undefined.

Displaying Pages Exclusively in a Hugo Menu

Sometimes you want to hide pages from the page menu but instead want to show them in a Hugo menu. For that you have two choices

1. Create a headless branch bundle, _index.md in its own folder with the below front matter. The branch bundle will not be contained in the sitemap.

   content/showcase/_index.en.md

   yaml toml json

   ---
   build:
     list: never
     publishResources: true
     render: always
   title: Showcase
   ---

   +++
   title = 'Showcase'
   
   [build]
     list = 'never'
     publishResources = true
     render = 'always'
   +++

   {
      "build": {
         "list": "never",
         "publishResources": true,
         "render": "always"
      },
      "title": "Showcase"
   }

2. Or, put a child page inside a headless branch bundle with the following front matter in the bundle. This causes the child but not the branch bundle to be contained in the sitemap.

   content/more/_index.en.md

   yaml toml json

   ---
   build:
     list: never
     publishResources: false
     render: never
   ---

   +++
   [build]
     list = 'never'
     publishResources = false
     render = 'never'
   +++

   {
      "build": {
         "list": "never",
         "publishResources": false,
         "render": "never"
      }
   }

   The child page can be any type of content.

   content/more/credits/_index.en.md

   yaml toml json

   ---
   title: Credits
   ---

   +++
   title = 'Credits'
   +++

   {
      "title": "Credits"
   }