Menus

You can do this:

• Place content in one or many menus
• Handle nested menus with unlimited depth
• Create menu entries without being attached to any content
• Distinguish active element (and active branch)

What is a Menu in Hugo?

A menu is a named array of menu entries accessible by name via the .Site.Menus site variable. For example, you can access your site’s main menu via .Site.Menus.main.

See the Menu Entry Properties for all the variables and functions related to a menu entry.

Add content to menus

Hugo allows you to add content to a menu via the content’s front matter.

Simple

If all you need to do is add an entry to a menu, the simple form works well.

A Single Menu

menu: main

menu = 'main'

{
   "menu": "main"
}

Multiple Menus

menu:
- main
- footer

menu = ['main', 'footer']

{
   "menu": [
      "main",
      "footer"
   ]
}

Advanced

menu:
  docs:
    parent: extras
    weight: 20

[menu]
  [menu.docs]
    parent = 'extras'
    weight = 20

{
   "menu": {
      "docs": {
         "parent": "extras",
         "weight": 20
      }
   }
}

Add Non-content Entries to a Menu

You can also add entries to menus that aren’t attached to a piece of content. This takes place in your Hugo project’s config file.

Here’s an example snippet pulled from a configuration file:

menu:
  main:
  - identifier: about
    name: about hugo
    pre: <i class='fa fa-heart'></i>
    url: /about/
    weight: -110
  - name: getting started
    post: <span class='alert'>New!</span>
    pre: <i class='fa fa-road'></i>
    url: /getting-started/
    weight: -100

[menu]
[[menu.main]]
  identifier = 'about'
  name = 'about hugo'
  pre = "<i class='fa fa-heart'></i>"
  url = '/about/'
  weight = -110
[[menu.main]]
  name = 'getting started'
  post = "<span class='alert'>New!</span>"
  pre = "<i class='fa fa-road'></i>"
  url = '/getting-started/'
  weight = -100

{
   "menu": {
      "main": [
         {
            "identifier": "about",
            "name": "about hugo",
            "pre": "\u003ci class='fa fa-heart'\u003e\u003c/i\u003e",
            "url": "/about/",
            "weight": -110
         },
         {
            "name": "getting started",
            "post": "\u003cspan class='alert'\u003eNew!\u003c/span\u003e",
            "pre": "\u003ci class='fa fa-road'\u003e\u003c/i\u003e",
            "url": "/getting-started/",
            "weight": -100
         }
      ]
   }
}

Nesting

All nesting of content is done via the parent field.

The parent of an entry should be the identifier of another entry. The identifier should be unique (within a menu).

The following order is used to determine an Identifier:

.Name > .LinkTitle > .Title

This means that .Title will be used unless .LinkTitle is present, etc. In practice, .Name and .Identifier are only used to structure relationships and therefore never displayed.

In this example, the top level of the menu is defined in your site config file. All content entries are attached to one of these entries via the .Parent field.

Params

You can also add user-defined content to menu items via the params field.

A common use case is to define a custom param to add a css class to a specific menu item.

menu:
  main:
  - identifier: about
    name: about hugo
    params:
      class: highlight-menu-item
    pre: <i class='fa fa-heart'></i>
    url: /about/
    weight: -110

[menu]
[[menu.main]]
  identifier = 'about'
  name = 'about hugo'
  pre = "<i class='fa fa-heart'></i>"
  url = '/about/'
  weight = -110
  [menu.main.params]
    class = 'highlight-menu-item'

{
   "menu": {
      "main": [
         {
            "identifier": "about",
            "name": "about hugo",
            "params": {
               "class": "highlight-menu-item"
            },
            "pre": "\u003ci class='fa fa-heart'\u003e\u003c/i\u003e",
            "url": "/about/",
            "weight": -110
         }
      ]
   }
}

Render Menus

See Menu Templates for information on how to render your site menus within your templates.