HUGO
News Docs Themes Community GitHub

Configure menus

Centrally define menu entries for one or more menus.

To understand Hugo’s menu system, please refer to the menus page.

There are three ways to define menu entries:

  1. Automatically
  2. In front matter
  3. In site configuration

This page covers the site configuration method.

Example

To define entries for a “main” menu:

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 Menus method on a Site object:

{{ range .Site.Menus.main }}
  ...
{{ end }}

See menu templates for a detailed example.

To define entries for a “footer” menu:

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
         }
      ]
   }
}

Access this menu structure in the same way:

{{ range .Site.Menus.footer }}
  ...
{{ end }}

Properties

Menu entries usually include at least three properties: name, weight, and either pageRef or url. Use pageRef for internal page destinations and url for external destinations.

These are the available menu entry properties:

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.
pageRef
(string) The logical path of the target page. For example:
page kindpageRef
home/
page/books/book-1
section/books
taxonomy/tags
term/tags/foo
url
(string) The destination URL. Use this for external destinations only.

Nested menu

This nested menu demonstrates some of the available properties:

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
         }
      ]
   }
}
Last updated: March 5, 2025 : content: Consolidate configuration documentation (b6cae5cbc)
Improve this page