menu-templates.md (5537B)
1 ---
2 title: Menu Templates
3 linktitle: Menu Templates
4 description: Menus are a powerful but simple feature for content management but can be easily manipulated in your templates to meet your design needs.
5 date: 2017-02-01
6 publishdate: 2017-02-01
7 lastmod: 2017-02-01
8 categories: [templates]
9 keywords: [lists,sections,menus]
10 menu:
11 docs:
12 title: "how to use menus in templates"
13 parent: "templates"
14 weight: 130
15 weight: 130
16 sections_weight: 130
17 draft: false
18 aliases: [/templates/menus/]
19 toc: false
20 ---
21
22 Hugo makes no assumptions about how your rendered HTML will be
23 structured. Instead, it provides all of the functions you will need to be
24 able to build your menu however you want.
25
26 The following is an example:
27
28 {{< code file="layouts/partials/sidebar.html" download="sidebar.html" >}}
29 <!-- sidebar start -->
30 <aside>
31 <ul>
32 {{ $currentPage := . }}
33 {{ range .Site.Menus.main }}
34 {{ if .HasChildren }}
35 <li class="{{ if $currentPage.HasMenuCurrent "main" . }}active{{ end }}">
36 <a href="#">
37 {{ .Pre }}
38 <span>{{ .Name }}</span>
39 </a>
40 </li>
41 <ul class="sub-menu">
42 {{ range .Children }}
43 <li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
44 <a href="{{ .URL }}">{{ .Name }}</a>
45 </li>
46 {{ end }}
47 </ul>
48 {{ else }}
49 <li>
50 <a href="{{ .URL }}">
51 {{ .Pre }}
52 <span>{{ .Name }}</span>
53 </a>
54 </li>
55 {{ end }}
56 {{ end }}
57 <li>
58 <a href="#" target="_blank">Hardcoded Link 1</a>
59 </li>
60 <li>
61 <a href="#" target="_blank">Hardcoded Link 2</a>
62 </li>
63 </ul>
64 </aside>
65 {{< /code >}}
66
67 {{% note "`absLangURL` and `relLangURL`" %}}
68 Use the [`absLangURL`](/functions/abslangurl) or [`relLangURL`](/functions/rellangurl) functions if your theme makes use of the [multilingual feature](/content-management/multilingual/). In contrast to `absURL` and `relURL`, these two functions add the correct language prefix to the url.
69 {{% /note %}}
70
71 ## Section Menu for Lazy Bloggers
72
73 To enable this menu, configure `sectionPagesMenu` in your site `config`:
74
75 ```
76 sectionPagesMenu = "main"
77 ```
78
79 The menu name can be anything, but take a note of what it is.
80
81 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:
82
83 ```
84 <nav class="sidebar-nav">
85 {{ $currentPage := . }}
86 {{ range .Site.Menus.main }}
87 <a class="sidebar-nav-item{{if or ($currentPage.IsMenuCurrent "main" .) ($currentPage.HasMenuCurrent "main" .) }} active{{end}}" href="{{ .URL }}" title="{{ .Title }}">{{ .Name }}</a>
88 {{ end }}
89 </nav>
90 ```
91
92 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.
93
94
95 ## Site Config menus
96
97 The above is all that's needed. But if you want custom menu items, e.g. changing weight, name, or link title attribute, you can define them manually in the site config file:
98
99 {{< code-toggle file="config" >}}
100 [[menu.main]]
101 name = "This is the blog section"
102 title = "blog section"
103 weight = -110
104 identifier = "blog"
105 url = "/blog/"
106 {{</ code-toggle >}}
107
108 {{% note %}}
109 The `identifier` *must* match the section name.
110 {{% /note %}}
111
112 ## Menu Entries from the Page's front matter
113
114 It's also possible to create menu entries from the page (i.e. the `.md`-file).
115
116 Here is a `yaml` example:
117
118 ```
119 ---
120 title: Menu Templates
121 linktitle: Menu Templates
122 menu:
123 docs:
124 title: "how to use menus in templates"
125 parent: "templates"
126 weight: 130
127 ---
128 ...
129 ```
130
131 {{% note %}}
132 You can define more than one menu. It also doesn't have to be a complex value,
133 `menu` can also be a string, an array of strings, or an array of complex values
134 like in the example above.
135 {{% /note %}}
136
137 ### Using .Page in Menus
138
139 If you use the front matter method of defining menu entries, you'll get access to the `.Page` variable.
140 This allows to use every variable that's reachable from the [page variable](/variables/page/).
141
142 This variable is only set when the menu entry is defined in the page's front matter.
143 Menu entries from the site config don't know anything about `.Page`.
144
145 That's why you have to use the go template's `with` keyword or something similar in your templating language.
146
147 Here's an example:
148
149 ```
150 <nav class="sidebar-nav">
151 {{ range .Site.Menus.main }}
152 <a href="{{ .URL }}" title="{{ .Title }}">
153 {{- .Name -}}
154 {{- with .Page -}}
155 <span class="date">
156 {{- dateFormat " (2006-01-02)" .Date -}}
157 </span>
158 {{- end -}}
159 </a>
160 {{ end }}
161 </nav>
162 ```
163
164 ## Using .Params in Menus
165
166 User-defined content on menu items are accessible via `.Params`.
167
168 Here's an example:
169
170 ```
171 <nav class="sidebar-nav">
172 {{ range .Site.Menus.main }}
173 <a href="{{ .URL }}" title="{{ .Title }}" class="{{ with .Params.class }}{{ . }}{{ end }}">
174 {{- .Name -}}
175 </a>
176 {{ end }}
177 </nav>
178 ```
179
180 {{% note %}}
181 With Menu-level .Params they can easily exist on one menu item but not another. It's recommended to access them gracefully using the [with function](/functions/with).
182 {{% /note %}}