hugo-theme-relearn/exampleSite/content/authoring/frontmatter/menu/_index.en.md

+++ categories = ["howto"] description = "Setting the behavior of the menus" frontmatter = ["alwaysopen", "collapsibleMenu", "linkTitle", "menuPost", "menuPre", "ordersectionsby", "sidebarmenus"] options = ["alwaysopen", "collapsibleMenu", "ordersectionsby", "sidebarmenus"] title = "Menus" weight = 2 +++

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

• {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} All configuration options in your hugo.toml apply to all menus but can be changed individually.

• {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} In case of page structure menus, individual configuration is done via a page's front matter.

• {{% badge color="blueviolet" icon="bars" title=" " %}}Menu{{% /badge %}}. In case of Hugo menus, individual configuration is done via a menu entry's configuration.

Expand State of Nested Sections

{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} You can change how submenus appear with alwaysopen.

{{% badge color="blueviolet" icon="bars" title=" " %}}Menu{{% /badge %}} 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

{{< multiconfig >}} alwaysopen = false {{< /multiconfig >}}

Expander for Nested Sections

{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Set collapsibleMenu=true to show submenus as collapsible trees with a clickable expander.

{{% badge color="blueviolet" icon="bars" title=" " %}}Menu{{% /badge %}} For Hugo menus, you have to set params.collapsibleMenu=true instead.

{{< multiconfig >}} collapsibleMenu = true {{< /multiconfig >}}

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 Sibling Menu Entries

By Weight

{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} {{% badge color="blueviolet" icon="bars" title=" " %}}Menu{{% /badge %}} Hugo provides a simple way to handle order of your entries by setting the weight front matter to a number.

{{< multiconfig>}} weight = 5 {{< /multiconfig >}}

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.

{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Use ordersectionsby to sort by other aspects. See the children shortcode for a complete list.

Hugo menus can only be sorted using the weight method.

{{< multiconfig >}} ordersectionsby = 'linktitle' {{< /multiconfig >}}

Title for Menu Entries

{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} 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.

{{% badge color="blueviolet" icon="bars" title=" " %}}Menu{{% /badge %}} 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

{{< multiconfig fm=true >}} title = 'Install on Linux' linkTitle = 'Linux' {{< /multiconfig >}}

Add Icon to a Menu Entry

{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} 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.

{{% badge color="blueviolet" icon="bars" title=" " %}}Menu{{% /badge %}} 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.

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

{{< multiconfig fm=true >}} title = 'GitHub Repo' menuPre = ' ' {{< /multiconfig >}}

Disable Parent 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 first-chapter/first-page 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 show an expander.

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

{{< multiconfig fm=true >}} [_build] render = 'never' {{< /multiconfig >}}

For Hugo Menus

Just don't give your parent menu entry configuration a url or pageRef

{{< multiconfig fm=true >}} menu.addendum name = 'Parent'

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

menu.addendum parent = 'Parent' name = 'Child 2' url = 'https://example.com/2' weight = 2 {{< /multiconfig >}}

Defining Menus

{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Menus are defined using the sidebarmenus option.

You can define as many menus, as you like. If you don't overwrite this option, the theme defaults to

{{< multiconfig >}} sidebarmenus = [ { type = 'page', identifier = 'home', main = true, disableTitle = true, pageRef = '' }, { type = 'menu', identifier = 'shortcuts', main = false, disableTitle = false }, ] {{< /multiconfig >}}

Parameter

Name	Default	Notes
type	<empty>	The type of menu. - page for a page menu - menu for a Hugo menu
identifier	<empty>	A unique identifier for this entry - for type=page an arbitrary name - for page=menu the identifier of the menu definition in your hugo.toml
main	see notes	Whether to add additional spacing and larger text to the menu - for type=page defaults to true - for page=menu defaults to false
disableTitle	see notes	Whether to print a title above the menu - for type=page defaults to true - for page=menu defaults to false
pageRef	<empty>	Only for type=page, the page path to start the menu tree. If not set, defaults to the home page.

Redefining Menus for Certain Pages

Suppose you are building a site that contains of a topmost blog and documentation section.

When the user is on one of the blog pages he should only see a menu containing all blog pages, while on a documentation page he should only see a menu containing all doc pages.

Directory structure:

content
├── 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

{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} Using Hugo's cascade feature, we can redefine the menus once in blog/_index.md and docs/_index.md setting sidebarmenus so they will be used in all children pages.

{{< multiconfig fm=true file="blog/_index.md">}} title = 'Blog' cascade [cascade.params] sidebarmenus = [ { type = 'page', identifier = 'blog', pageRef = '/blog' }, ] {{< /multiconfig >}}

{{< multiconfig fm=true file="docs/_index.md">}} title = 'Documentation' cascade [cascade.params] sidebarmenus = [ { type = 'page', identifier = 'docs', pageRef = '/docs' }, ] {{< /multiconfig >}}