Menus

Create menus by defining entries, localizing each entry, and rendering the resulting data structure.

Overview #

To create a menu for your site:

Define the menu entries
[Localize] each entry
Render the menu with a [template]

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 a menu entry for each top-level [section] of your site, enable the section pages menu in your site configuration.

hugo.

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:

content/about.md

---
menus: main
title: About
---

+++
menus = 'main'
title = 'About'
+++

{
   "menus": "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:

content/contact.md

---
menus:
- main
- footer
title: Contact
---

+++
menus = ['main', 'footer']
title = 'Contact'
+++

{
   "menus": [
      "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 same name, or when localizing the name 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) The identifier of the parent menu entry. If identifier is not defined, use name. 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 HTML title 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:

content/products/software.md

---
menus:
  main:
    params:
      class: center
    parent: Products
    pre: <i class="fa-solid fa-code"></i>
    weight: 20
title: Software
---

+++
title = 'Software'
[menus]
  [menus.main]
    parent = 'Products'
    pre = '<i class="fa-solid fa-code"></i>'
    weight = 20
    [menus.main.params]
      class = 'center'
+++

{
   "menus": {
      "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:

hugo.

menus:
  main:
  - name: Home
    pageRef: /
    weight: 10
  - name: Products
    pageRef: /products
    weight: 20
  - name: Services
    pageRef: /services
    weight: 30

[menus]
[[menus.main]]
    name = 'Home'
    pageRef = '/'
    weight = 10
[[menus.main]]
    name = 'Products'
    pageRef = '/products'
    weight = 20
[[menus.main]]
    name = 'Services'
    pageRef = '/services'
    weight = 30

{
   "menus": {
      "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:

hugo.

menus:
  footer:
  - name: Terms
    pageRef: /terms
    weight: 10
  - name: Privacy
    pageRef: /privacy
    weight: 20

[menus]
[[menus.footer]]
    name = 'Terms'
    pageRef = '/terms'
    weight = 10
[[menus.footer]]
    name = 'Privacy'
    pageRef = '/privacy'
    weight = 20

{
   "menus": {
      "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 and pageRef for internal links
Specify name and url for external links

pageRef: (string) The logical path of the target page, relative to the content 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:

hugo.

menus:
  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

[menus]
[[menus.main]]
    name = 'Products'
    pageRef = '/products'
    weight = 10
[[menus.main]]
    name = 'Hardware'
    pageRef = '/products/hardware'
    parent = 'Products'
    weight = 1
[[menus.main]]
    name = 'Software'
    pageRef = '/products/software'
    parent = 'Products'
    weight = 2
[[menus.main]]
    name = 'Services'
    pageRef = '/services'
    weight = 20
[[menus.main]]
    name = 'Hugo'
    pre = '<i class="fa fa-heart"></i>'
    url = 'https://gohugo.io/'
    weight = 30
    [menus.main.params]
      rel = 'external'

{
   "menus": {
      "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].