Menus
Overview
To create a menu for your site:
Create multiple menus, either flat or nested. For example, create a main menu for the header, and a separate menu for the footer.
There are three ways to define menu entries:
- Automatically
- In front matter
- In site configuration
Define automatically
To automatically define menu entries for each top-level section of your site, enable the section pages menu in your site configuration.
sectionPagesMenu: main
sectionPagesMenu = 'main'
{
"sectionPagesMenu": "main"
}
This creates a menu structure that you can access with site.Menus.main
in your templates. See menu templates for details.
Define in front matter
To add a page to the “main” menu:
---
menu: main
title: About
---
+++
menu = 'main'
title = 'About'
+++
{
"menu": "main",
"title": "About"
}
Access the entry with site.Menus.main
in your templates. See menu templates for details.
To add a page to the “main” and “footer” menus:
---
menu:
- main
- footer
title: Contact
---
+++
menu = ['main', 'footer']
title = 'Contact'
+++
{
"menu": [
"main",
"footer"
],
"title": "Contact"
}
Access the entry with site.Menus.main
and site.Menus.footer
in your templates. See menu templates for details.
Properties
Use these properties when defining menu entries in front matter:
- identifier
- (
string
) Required when two or more menu entries have the samename
, or when localizing thename
using translation tables. Must start with a letter, followed by letters, digits, or underscores. - name
- (
string
) The text to display when rendering the menu entry. - params
- (
map
) User-defined properties for the menu entry. - parent
- (
string
) Theidentifier
of the parent menu entry. Ifidentifier
is not defined, usename
. Required for child entries in a nested menu. - post
- (
string
) The HTML to append when rendering the menu entry. - pre
- (
string
) The HTML to prepend when rendering the menu entry. - title
- (
string
) The HTMLtitle
attribute of the rendered menu entry. - weight
- (
int
) A non-zero integer indicating the entry’s position relative the root of the menu, or to its parent for a child entry. Lighter entries float to the top, while heavier entries sink to the bottom.
Example
This front matter menu entry demonstrates some of the available properties:
---
menu:
main:
params:
class: center
parent: Products
pre: <i class="fa-solid fa-code"></i>
weight: 20
title: Software
---
+++
title = 'Software'
[menu]
[menu.main]
parent = 'Products'
pre = '<i class="fa-solid fa-code"></i>'
weight = 20
[menu.main.params]
class = 'center'
+++
{
"menu": {
"main": {
"params": {
"class": "center"
},
"parent": "Products",
"pre": "\u003ci class=\"fa-solid fa-code\"\u003e\u003c/i\u003e",
"weight": 20
}
},
"title": "Software"
}
Access the entry with site.Menus.main
in your templates. See menu templates for details.
Define in site configuration
To define entries for the “main” menu:
menu:
main:
- name: Home
pageRef: /
weight: 10
- name: Products
pageRef: /products
weight: 20
- name: Services
pageRef: /services
weight: 30
[menu]
[[menu.main]]
name = 'Home'
pageRef = '/'
weight = 10
[[menu.main]]
name = 'Products'
pageRef = '/products'
weight = 20
[[menu.main]]
name = 'Services'
pageRef = '/services'
weight = 30
{
"menu": {
"main": [
{
"name": "Home",
"pageRef": "/",
"weight": 10
},
{
"name": "Products",
"pageRef": "/products",
"weight": 20
},
{
"name": "Services",
"pageRef": "/services",
"weight": 30
}
]
}
}
This creates a menu structure that you can access with site.Menus.main
in your templates. See menu templates for details.
To define entries for the “footer” menu:
menu:
footer:
- name: Terms
pageRef: /terms
weight: 10
- name: Privacy
pageRef: /privacy
weight: 20
[menu]
[[menu.footer]]
name = 'Terms'
pageRef = '/terms'
weight = 10
[[menu.footer]]
name = 'Privacy'
pageRef = '/privacy'
weight = 20
{
"menu": {
"footer": [
{
"name": "Terms",
"pageRef": "/terms",
"weight": 10
},
{
"name": "Privacy",
"pageRef": "/privacy",
"weight": 20
}
]
}
}
This creates a menu structure that you can access with site.Menus.footer
in your templates. See menu templates for details.
Properties
Each menu entry defined in site configuration requires two or more properties:
- Specify
name
andpageRef
for internal links - Specify
name
andurl
for external links
- pageRef
- (
string
) The file path of the target page, relative to thecontent
directory. Omit language code and file extension. Required for internal links.
Kind | pageRef |
---|---|
home | / |
page | /books/book-1 |
section | /books |
taxonomy | /tags |
term | /tags/foo |
- url
- (
string
) Required for external links.
Example
This nested menu demonstrates some of the available properties:
menu:
main:
- name: Products
pageRef: /products
weight: 10
- name: Hardware
pageRef: /products/hardware
parent: Products
weight: 1
- name: Software
pageRef: /products/software
parent: Products
weight: 2
- name: Services
pageRef: /services
weight: 20
- name: Hugo
params:
rel: external
pre: <i class="fa fa-heart"></i>
url: https://gohugo.io/
weight: 30
[menu]
[[menu.main]]
name = 'Products'
pageRef = '/products'
weight = 10
[[menu.main]]
name = 'Hardware'
pageRef = '/products/hardware'
parent = 'Products'
weight = 1
[[menu.main]]
name = 'Software'
pageRef = '/products/software'
parent = 'Products'
weight = 2
[[menu.main]]
name = 'Services'
pageRef = '/services'
weight = 20
[[menu.main]]
name = 'Hugo'
pre = '<i class="fa fa-heart"></i>'
url = 'https://gohugo.io/'
weight = 30
[menu.main.params]
rel = 'external'
{
"menu": {
"main": [
{
"name": "Products",
"pageRef": "/products",
"weight": 10
},
{
"name": "Hardware",
"pageRef": "/products/hardware",
"parent": "Products",
"weight": 1
},
{
"name": "Software",
"pageRef": "/products/software",
"parent": "Products",
"weight": 2
},
{
"name": "Services",
"pageRef": "/services",
"weight": 20
},
{
"name": "Hugo",
"params": {
"rel": "external"
},
"pre": "\u003ci class=\"fa fa-heart\"\u003e\u003c/i\u003e",
"url": "https://gohugo.io/",
"weight": 30
}
]
}
}
This creates a menu structure that you can access with site.Menus.main
in your templates. See menu templates for details.
Localize
Hugo provides two methods to localize your menu entries. See multilingual.
Render
See menu templates.