menus.md (4111B)
1 ---
2 title: Menus
3 linktitle: Menus
4 description: Hugo has a simple yet powerful menu system.
5 date: 2017-02-01
6 publishdate: 2017-02-01
7 lastmod: 2017-03-31
8 categories: [content management]
9 keywords: [menus]
10 draft: false
11 menu:
12 docs:
13 parent: "content-management"
14 weight: 120
15 weight: 120
16 aliases: [/extras/menus/]
17 toc: true
18 ---
19
20 {{% note "Lazy Blogger"%}}
21 If all you want is a simple menu for your sections, see the ["Section Menu for Lazy Bloggers" in Menu Templates](/templates/menu-templates/#section-menu-for-lazy-bloggers).
22 {{% /note %}}
23
24 You can do this:
25
26 * Place content in one or many menus
27 * Handle nested menus with unlimited depth
28 * Create menu entries without being attached to any content
29 * Distinguish active element (and active branch)
30
31 ## What is a Menu in Hugo?
32
33 A **menu** is a named array of menu entries accessible by name via the [`.Site.Menus` site variable][sitevars]. For example, you can access your site's `main` menu via `.Site.Menus.main`.
34
35 {{% note "Menus on Multilingual Sites" %}}
36 If you make use of the [multilingual feature](/content-management/multilingual/), you can define language-independent menus.
37 {{% /note %}}
38
39 See the [Menu Entry Properties][me-props] for all the variables and functions related to a menu entry.
40
41 ## Add content to menus
42
43 Hugo allows you to add content to a menu via the content's [front matter](/content-management/front-matter/).
44
45 ### Simple
46
47 If all you need to do is add an entry to a menu, the simple form works well.
48
49 #### A Single Menu
50
51 {{< code-toggle >}}
52 menu: "main"
53 {{< /code-toggle >}}
54
55 #### Multiple Menus
56
57 {{< code-toggle >}}
58 menu: ["main", "footer"]
59 {{< /code-toggle >}}
60
61 #### Advanced
62
63 {{< code-toggle >}}
64 menu:
65 docs:
66 parent: 'extras'
67 weight: 20
68 {{< /code-toggle >}}
69
70 ## Add Non-content Entries to a Menu
71
72 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][config].
73
74 Here’s an example snippet pulled from a configuration file:
75
76 {{< code-toggle file="config" >}}
77 [[menu.main]]
78 name = "about hugo"
79 pre = "<i class='fa fa-heart'></i>"
80 weight = -110
81 identifier = "about"
82 url = "/about/"
83 [[menu.main]]
84 name = "getting started"
85 pre = "<i class='fa fa-road'></i>"
86 post = "<span class='alert'>New!</span>"
87 weight = -100
88 url = "/getting-started/"
89 {{< /code-toggle >}}
90
91 {{% note %}}
92 The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will override the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`.
93 {{% /note %}}
94
95 ## Nesting
96
97 All nesting of content is done via the `parent` field.
98
99 The parent of an entry should be the identifier of another entry. The identifier should be unique (within a menu).
100
101 The following order is used to determine an Identifier:
102
103 `.Name > .LinkTitle > .Title`
104
105 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.
106
107 In this example, the top level of the menu is defined in your [site `config` file][config]. All content entries are attached to one of these entries via the `.Parent` field.
108
109 ## Params
110
111 You can also add user-defined content to menu items via the `params` field.
112
113 A common use case is to define a custom param to add a css class to a specific menu item.
114
115 {{< code-toggle file="config" >}}
116 [[menu.main]]
117 name = "about hugo"
118 pre = "<i class='fa fa-heart'></i>"
119 weight = -110
120 identifier = "about"
121 url = "/about/"
122 [menu.main.params]
123 class = "highlight-menu-item"
124 {{</ code-toggle >}}
125
126 ## Render Menus
127
128 See [Menu Templates](/templates/menu-templates/) for information on how to render your site menus within your templates.
129
130 [config]: /getting-started/configuration/
131 [multilingual]: /content-management/multilingual/
132 [sitevars]: /variables/
133 [me-props]: /variables/menus/