1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
---
title: Menus
description: Create menus by defining entries, localizing each entry, and rendering the resulting data structure.
categories: [content management]
keywords: [menus]
menu:
docs:
parent: content-management
weight: 190
weight: 190
toc: true
aliases: [/extras/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
1. In front matter
1. In site configuration
{{% note %}}
Although you can use these methods in combination when defining a menu, the menu will be easier to conceptualize and maintain if you use one method throughout the site.
{{% /note %}}
## 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.
{{< code-toggle file=hugo >}}
sectionPagesMenu = "main"
{{< /code-toggle >}}
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:
{{< code-toggle file=content/about.md fm=true >}}
title = 'About'
menus = 'main'
{{< /code-toggle >}}
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:
{{< code-toggle file=content/contact.md fm=true >}}
title = 'Contact'
menus = ['main','footer']
{{< /code-toggle >}}
Access the entry with `site.Menus.main` and `site.Menus.footer` in your templates. See [menu templates] for details.
{{% note %}}
The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`.
{{% /note %}}
### Properties {#properties-front-matter}
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 {#example-front-matter}
This front matter menu entry demonstrates some of the available properties:
{{< code-toggle file=content/products/software.md fm=true >}}
title = 'Software'
[[menus.main]]
parent = 'Products'
weight = 20
pre = '<i class="fa-solid fa-code"></i>'
[menus.main.params]
class = 'center'
{{< /code-toggle >}}
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:
{{< code-toggle file=hugo >}}
[[menus.main]]
name = 'Home'
pageRef = '/'
weight = 10
[[menus.main]]
name = 'Products'
pageRef = '/products'
weight = 20
[[menus.main]]
name = 'Services'
pageRef = '/services'
weight = 30
{{< /code-toggle >}}
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:
{{< code-toggle file=hugo >}}
[[menus.footer]]
name = 'Terms'
pageRef = '/terms'
weight = 10
[[menus.footer]]
name = 'Privacy'
pageRef = '/privacy'
weight = 20
{{< /code-toggle >}}
This creates a menu structure that you can access with `site.Menus.footer` in your templates. See [menu templates] for details.
{{% note %}}
The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`.
{{% /note %}}
### Properties {#properties-site-configuration}
{{% note %}}
The [properties available to entries defined in front matter] are also available to entries defined in site configuration.
[properties available to entries defined in front matter]: /content-management/menus/#properties-front-matter
{{% /note %}}
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 {#example-site-configuration}
This nested menu demonstrates some of the available properties:
{{< code-toggle file=hugo >}}
[[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'
{{< /code-toggle >}}
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].
[localize]: /content-management/multilingual/#menus
[menu templates]: /templates/menu/
[multilingual]: /content-management/multilingual/#menus
[section]: /getting-started/glossary/#section
[template]: /templates/menu/
|
