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
hugo.toml
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=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=false
- if not overridden, all other entries of levels besides the first behave like they would have been given
alwaysopen=true
- all visible entries show their immediate child entries if
alwaysopen=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=true
to show submenus as collapsible trees with a clickable expander.
Menu For Hugo menus, you have to set params.collapsibleMenu=true
instead.
[params]
collapsibleMenu = true
params:
collapsibleMenu: true
{
"params": {
"collapsibleMenu": true
}
}
Warning
Using this option may cause degraded build performance by slowing down your build process.
This is usually the case for menus with many entries and happens for page menus as well as for Hugo menus.
We’ve seen builds taking 2 minutes with 1000+ pages, and over 30 minutes with 5000+ pages when using a page menu.
This happens because each new page affects all other pages, leading to exponentially longer build times.
Ordering Menu Entries
By Weight
Front Matter Menu Hugo provides a simple way to handle order of your entries by setting the weight
front matter to a number.
Hugo menus can only be sorted using the weight method.
weight = 5
weight: 5
{
"weight": 5
}
By Other
Using the weight
for sorting can get cumbersome if you, for example, just want to sort alphabetically. Each time you add a new page in the set of pages, you may have to renumber some or all of them to make space for the new page.
Option Front Matter Use ordersectionsby
to sort by other aspects. See the children shortcode for a complete list.
[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.
+++
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"
}
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]
[[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, the theme supports one additional Hugo menu below the page menu in the sidebar named shortcuts
. You only need to configure it in your hugo.toml
to appear in your 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 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 with disableShortcutsTitle=true
.
[params]
disableShortcutsTitle = true
params:
disableShortcutsTitle: true
{
"params": {
"disableShortcutsTitle": true
}
}
To change the title, override your translation file.
[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 disableMenuTitle=false
for each sidebar menu configuration.
Front Matter For page menus, set the menuTitle
front matter for the root page of the menu. For example in the home page for the default sidebar menu. If no menuTitle
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]
[[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
---
{
"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 boxsidebarmenus
: the scrolling area below the search boxsidebarfootermenus
: 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 hugo.toml
, 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
- a divider to separate from the
This comes down to the following pseudo default configuration.
[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
{
"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 fordisableTitle
will be determined by your configuration fordisableShortcutsTitle
.
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 now starting page is given, the home page is used.
Name | Default | Notes |
---|---|---|
type | <empty> | page , required |
identifier | <empty> | Optional with no special meaning besides for error messages |
main | true |
Whether to add additional spacing and larger text to the menu |
disableTitle | true |
Whether to print a title above the menu |
pageRef | / |
The path of the page to start the menu tree |
Hugo Menu
The Hugo menu generates a menu tree out of a Hugo menu definition with the same identifier
.
Name | Default | Notes |
---|---|---|
type | <empty> | menu , required |
identifier | <empty> | The identifier of the menu definition in your hugo.toml |
main | false |
Whether to add additional spacing and larger text to the menu |
disableTitle | false |
Whether to print a title above the menu; for the predefined shortcuts menu, accounts to the setting of disableShortcutsTitle |
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.
Name | Default | Notes |
---|---|---|
type | <empty> | custom , required |
identifier | <empty> | Optional with no special meaning besides for error messages |
main | false |
Whether to add additional spacing and larger text to the menu |
elements | <empty> | The list of snippets, contained in layouts/partials/sidebar/element , to be displayed. See below. |
A HTML snippet has its own parameter. Your self-defined snippets can contain 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.
Name | Default | Notes |
---|---|---|
type | <empty> | The theme ships with the following snippets: - languageswitcher : will display the language switcher- variantswitcher : will display the variant switcher- versionswitcher : will display the version switcher- historyclearer : will display a button to clear the history of visited links |
icon | see notes | Font Awesome icon name set to the left of the list entry. Depending on the type there is a default icon. Any given value will overwrite the default. |
Divider
A horizontal ruler
Name | Default | Notes |
---|---|---|
type | <empty> | divider |
identifier | <empty> | Optional with no special meaning besides for error messages |
Example
The following example configures the language switcher and history clearer into the menu header, only shows the the page menu in the main sidebar section and keeps the 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: page
{
"params": {
"sidebarfootermenus": [],
"sidebarheadermenus": [
{
"elements": [
{
"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:
- content
- log
- first-day.md
- second-day.md
- third-day.md
- _index.md
- ship
- cargo.md
- midst.md
- upper.md
- _index.md
- _index.md
- log
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.
+++
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": "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: page
- identifier: shortcuts
type: menu
title: The Ship
---
{
"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
- content
- log
- first-day.md
- second-day.md
- third-day.md
- _index.md
- burning-sail-incident.md
- kraken-incident.md
- _index.md
- log
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
+++
title = "The Crow's Nest Incident"
[params]
menuPageRef = '/log/third-day'
+++
---
params:
menuPageRef: /log/third-day
title: The Crow's Nest Incident
---
{
"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
-
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+++ 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" }
-
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+++ [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+++ title = 'Credits' +++
--- title: Credits ---
{ "title": "Credits" }