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
|
---
lastmod: 2015-08-04
date: 2014-05-14T02:36:37Z
toc: true
menu:
main:
parent: extras
next: /extras/permalinks
prev: /extras/livereload
title: Menus
weight: 60
---
Hugo has a simple yet powerful menu system that permits content to be
placed in menus with a good degree of control without a lot of work.
*TIP:* If all you want is a simple menu for your sections, see [Section Menu for "the Lazy Blogger"]({{< relref "#section-menu-for-the-lazy-blogger" >}}).
Some of the features of Hugo Menus:
* 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?
A menu is a named array of menu entries accessible on the site under
`.Site.Menus` by name. For example, if I have a menu called `main`, I would
access it via `.Site.Menus.main`.
A menu entry has the following properties:
* **URL** string
* **Name** string
* **Menu** string
* **Identifier** string
* **Pre** template.HTML
* **Post** template.HTML
* **Weight** int
* **Parent** string
* **Children** Menu
And the following functions:
* **HasChildren** bool
Additionally, there are some relevant functions available on the page:
* **IsMenuCurrent** (menu string, menuEntry *MenuEntry ) bool
* **HasMenuCurrent** (menu string, menuEntry *MenuEntry) bool
## Adding content to menus
Hugo supports a couple of different methods of adding a piece of content
to the 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"
---
**Multiple menus:**
---
menu: ["main", "footer"]
---
### Advanced
If more control is required, then the advanced approach gives you the
control you want. All of the menu entry properties listed above are
available.
---
menu:
main:
parent: 'extras'
weight: 20
---
## Adding (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 the sitewide [config file](/overview/configuration/).
Here’s an example `config.toml`:
[[menu.main]]
name = "about hugo"
pre = "<i class='fa fa-heart'></i>"
weight = -110
identifier = "about"
url = "/about/"
[[menu.main]]
name = "getting started"
pre = "<i class='fa fa-road'></i>"
weight = -100
url = "/getting-started/"
And the equivalent example `config.yaml`:
---
menu:
main:
- Name: "about hugo"
Pre: "<i class='fa fa-heart'></i>"
Weight: -110
Identifier: "about"
URL: "/about/"
- Name: "getting started"
Pre: "<i class='fa fa-road'></i>"
Weight: -100
URL: "/getting-started/"
---
**NOTE:** The URLs must be relative to the context root. If the `BaseURL` is `http://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`.
## Nesting
All nesting of content is done via the `parent` field.
The parent of an entry should be the identifier of another entry.
Identifier should be unique (within a menu).
The following order is used to determine identity Identifier > Name >
LinkTitle > Title. This means that the title will be used unless
linktitle is present, etc. In practice Name and Identifier are never
displayed and only used to structure relationships.
In this example, the top level of the menu is defined in the config file
and all content entries are attached to one of these entries via the
`parent` field.
## Rendering menus
Hugo makes no assumptions about how your rendered HTML will be
structured. Instead, it provides all of the functions you will need to be
able to build your menu however you want.
The following is an example:
<!--sidebar start-->
<aside>
<div id="sidebar" class="nav-collapse">
<!-- sidebar menu start-->
<ul class="sidebar-menu">
{{ $currentNode := . }}
{{ range .Site.Menus.main }}
{{ if .HasChildren }}
<li class="sub-menu{{if $currentNode.HasMenuCurrent "main" . }} active{{end}}">
<a href="javascript:;" class="">
{{ .Pre }}
<span>{{ .Name }}</span>
<span class="menu-arrow arrow_carrot-right"></span>
</a>
<ul class="sub">
{{ range .Children }}
<li{{if $currentNode.IsMenuCurrent "main" . }} class="active"{{end}}><a href="{{.Permalink}}"> {{ .Name }} </a> </li>
{{ end }}
</ul>
{{else}}
<li>
<a class="" href="{{.Permalink}}">
{{ .Pre }}
<span>{{ .Name }}</span>
</a>
{{end}}
</li>
{{end}}
<li> <a href="https://github.com/spf13/hugo/issues" target="blank">Questions and Issues</a> </li>
<li> <a href="#" target="blank">Edit this Page</a> </li>
</ul>
<!-- sidebar menu end-->
</div>
</aside>
<!--sidebar end-->
## Section Menu for "the Lazy Blogger"
To enable this menu, add this to your site config, i.e. `config.toml`:
```
SectionPagesMenu = "main"
```
The menu name can be anything, but take a note of what it is.
This will create a menu with all the sections as menu items and all the sections' pages as "shadow-members". The _shadow_ implies that the pages isn't represented by a menu-item themselves, but this enables you to create a top-level menu like this:
```
<nav class="sidebar-nav">
{{ $currentNode := . }}
{{ range .Site.Menus.main }}
<a class="sidebar-nav-item{{if or ($currentNode.IsMenuCurrent "main" .) ($currentNode.HasMenuCurrent "main" .) }} active{{end}}" href="{{.Permalink}}">{{ .Name }}</a>
{{ end }}
</nav>
```
In the above, the menu item is marked as active if on the current section's list page or on a page in that section.
The above is all that's needed. But if you want custom menu items, e.g. changing weight or name, you can define them manually in the site config, i.e. `config.toml`:
```
[[menu.main]]
name = "This is the blog section"
weight = -110
identifier = "blog"
url = "/blog/"
```
**Note** that the `identifier` must match the section name.
|
