CONTENT MANAGEMENT

Menus

Overview

To create a menu for your site:

  1. Define the menu entries
  2. Localize each entry
  3. 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:

  1. Automatically
  2. In front matter
  3. 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.

config.
      
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
      
---
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:

content/contact.md
      
---
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 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
      
---
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:

config.
      
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:

config.
      
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 and pageRef for internal links
  • Specify name and url for external links
pageRef
(string) The file path of the target page, relative to the content directory. Omit language code and file extension. Required for internal links.
KindpageRef
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:

config.
      
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.

See Also

Last updated: April 15, 2023: Clarify pageRef menu property (#2059) (5d392c3d)
Improve this page