mirror of
https://github.com/gohugoio/hugo.git
synced 2026-08-24 15:28:54 +00:00
Correct and improve menu documentation (#2010)
This is a substantial rewrite of pages describing: - Menu entries - Menu templates - Menu localization - Variables and methods available to templates Closes #1594 Closes #1752
This commit is contained in:
Joe Mooring
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: Menus
|
||||
linkTitle: Menus
|
||||
description: Hugo has a simple yet powerful menu system.
|
||||
description: Create menus by defining entries, localizing each entry, and rendering the resulting data structure.
|
||||
categories: [content management]
|
||||
keywords: [menus]
|
||||
menu:
|
||||
@@ -13,117 +13,206 @@ weight: 190
|
||||
aliases: [/extras/menus/]
|
||||
---
|
||||
|
||||
{{% note "Lazy Blogger"%}}
|
||||
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).
|
||||
{{% /note %}}
|
||||
## Overview
|
||||
|
||||
You can do this:
|
||||
To create a menu for your site:
|
||||
|
||||
* 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)
|
||||
1. Define the menu entries
|
||||
2. [Localize] each entry
|
||||
3. Render the menu with a [template]
|
||||
|
||||
## What is a Menu in Hugo?
|
||||
Create multiple menus, either flat or nested. For example, create a main menu for the header, and a separate menu for the footer.
|
||||
|
||||
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`.
|
||||
There are three ways to define menu entries:
|
||||
|
||||
{{% note "Menus on Multilingual Sites" %}}
|
||||
If you make use of the [multilingual feature](/content-management/multilingual/), you can define language-independent menus.
|
||||
{{% /note %}}
|
||||
|
||||
See the [Menu Entry Properties][me-props] 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](/content-management/front-matter/).
|
||||
|
||||
### Simple
|
||||
|
||||
If all you need to do is add an entry to a menu, the simple form works well.
|
||||
|
||||
#### A Single Menu
|
||||
|
||||
{{< code-toggle >}}
|
||||
menu: "main"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
#### Multiple Menus
|
||||
|
||||
{{< code-toggle >}}
|
||||
menu: ["main", "footer"]
|
||||
{{< /code-toggle >}}
|
||||
|
||||
#### Advanced
|
||||
|
||||
{{< code-toggle >}}
|
||||
menu:
|
||||
docs:
|
||||
parent: 'extras'
|
||||
weight: 20
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## 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][config] (see [Menu Entry Properties][me-props] for full details of available variables).
|
||||
|
||||
Here’s an example snippet pulled from a configuration file:
|
||||
|
||||
{{< code-toggle file="config" >}}
|
||||
[[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>"
|
||||
post = "<span class='alert'>New!</span>"
|
||||
weight = -100
|
||||
url = "/getting-started/"
|
||||
{{< /code-toggle >}}
|
||||
1. Automatically
|
||||
1. In front matter
|
||||
1. In site configuration
|
||||
|
||||
{{% note %}}
|
||||
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`.
|
||||
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 %}}
|
||||
|
||||
## Nesting
|
||||
## Define automatically
|
||||
|
||||
All nesting of content is done via the `parent` field.
|
||||
To automatically define menu entries for each top-level section of your site, enable the section pages menu in your site configuration.
|
||||
q
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
sectionPagesMenu = "main"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The parent of an entry should be the identifier of another entry. The identifier should be unique (within a menu).
|
||||
This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details.
|
||||
|
||||
The following order is used to determine an Identifier:
|
||||
## Define in front matter
|
||||
|
||||
`.Name > .LinkTitle > .Title`
|
||||
To add a page to the "main" menu:
|
||||
|
||||
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.
|
||||
{{< code-toggle file="content/about.md" copy=false fm=true >}}
|
||||
title = 'About'
|
||||
menu = 'main'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
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.
|
||||
Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
|
||||
|
||||
## Params
|
||||
To add a page to the "main" and "footer" menus:
|
||||
|
||||
You can also add user-defined content to menu items via the `params` field.
|
||||
{{< code-toggle file="content/contact.md" copy=false fm=true >}}
|
||||
title = 'Contact'
|
||||
menu = ['main','footer']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
A common use case is to define a custom param to add a css class to a specific menu item.
|
||||
Access the entry with `site.Menus.main` and `site.Menus.footer` in your templates. See [menu templates] for details.
|
||||
|
||||
{{< code-toggle file="config" >}}
|
||||
### 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" copy=false fm=true >}}
|
||||
title = 'Software'
|
||||
[menu.main]
|
||||
parent = 'Products'
|
||||
weight = 20
|
||||
pre = '<i class="fa-solid fa-code"></i>'
|
||||
[menu.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="config" copy=false >}}
|
||||
[[menu.main]]
|
||||
name = "about hugo"
|
||||
pre = "<i class='fa fa-heart'></i>"
|
||||
weight = -110
|
||||
identifier = "about"
|
||||
url = "/about/"
|
||||
[menu.main.params]
|
||||
class = "highlight-menu-item"
|
||||
{{</ code-toggle >}}
|
||||
name = 'Home'
|
||||
pageRef = '/'
|
||||
weight = 10
|
||||
|
||||
## Render Menus
|
||||
[[menu.main]]
|
||||
name = 'Products'
|
||||
pageRef = '/products'
|
||||
weight = 20
|
||||
|
||||
See [Menu Templates](/templates/menu-templates/) for information on how to render your site menus within your templates.
|
||||
[[menu.main]]
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 30
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[config]: /getting-started/configuration/
|
||||
[multilingual]: /content-management/multilingual/
|
||||
[sitevars]: /variables/
|
||||
[me-props]: /variables/menus/
|
||||
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="config" copy=false >}}
|
||||
[[menu.footer]]
|
||||
name = 'Terms'
|
||||
pageRef = '/terms'
|
||||
weight = 10
|
||||
|
||||
[[menu.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.
|
||||
|
||||
### Properties {#properties-site-configuration}
|
||||
|
||||
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 file path of the target page, relative to the `content` directory. Required for *internal* links.
|
||||
|
||||
url
|
||||
: (string) Required for *external* links.
|
||||
|
||||
{{% note %}}
|
||||
The [properties] available to entries defined in front matter are also available to entries defined in site configuration.
|
||||
|
||||
[properties]: /content-management/menus/#properties-front-matter
|
||||
{{% /note %}}
|
||||
|
||||
### Example {#example-site-configuration}
|
||||
|
||||
This nested menu demonstrates some of the available properties:
|
||||
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
[[menu.main]]
|
||||
name = 'Products'
|
||||
pageRef = '/products'
|
||||
weight = 10
|
||||
|
||||
[[menu.main]]
|
||||
name = 'Hardware'
|
||||
pageRef = '/products/hardware'
|
||||
parent = 'Products'
|
||||
weight = 1
|
||||
|
||||
[[menu.main]]
|
||||
name = 'Software'
|
||||
pageRef = '/products/software'
|
||||
parent = 'Products'
|
||||
weight = 2
|
||||
|
||||
[[menu.main]]
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 20
|
||||
|
||||
[[menu.main]]
|
||||
name = 'Hugo'
|
||||
pre = '<i class="fa fa-heart"></i>'
|
||||
url = 'https://gohugo.io/'
|
||||
weight = 30
|
||||
[menu.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-templates/
|
||||
[multilingual]: /content-management/multilingual/#menus
|
||||
[template]: /templates/menu-templates/
|
||||
|
||||
@@ -468,76 +468,91 @@ See [lang.FormatPercent] for details.
|
||||
|
||||
## Menus
|
||||
|
||||
You can define your menus for each language independently. Creating multilingual menus works just like [creating regular menus][menus], except they're defined in language-specific blocks in the configuration file:
|
||||
Localization of menu entries depends on the how you define them:
|
||||
|
||||
{{< code-toggle file="config" >}}
|
||||
defaultContentLanguage = "en"
|
||||
- When you define menu entries [automatically] using the section pages menu, you must use translation tables to localize each entry.
|
||||
- When you define menu entries [in front matter], they are already localized based on the front matter itself. If the front matter values are insufficient, use translation tables to localize each entry.
|
||||
- When you define menu entries [in site configuration], you can (a) use translation tables, or (b) create language-specific menu entries under each language key.
|
||||
|
||||
[languages.en]
|
||||
weight = 0
|
||||
languageName = "English"
|
||||
### Use translation tables
|
||||
|
||||
[[languages.en.menu.main]]
|
||||
url = "/"
|
||||
name = "Home"
|
||||
weight = 0
|
||||
|
||||
[languages.de]
|
||||
weight = 10
|
||||
languageName = "Deutsch"
|
||||
|
||||
[[languages.de.menu.main]]
|
||||
url = "/"
|
||||
name = "Startseite"
|
||||
weight = 0
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu in the current language. Note that `absLangURL` below will link to the correct locale of your website. Without it, menu entries in all languages would link to the English version, since it's the default content language that resides in the root directory.
|
||||
When rendering the text that appears in menu each entry, the [example menu template] does this:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{- $currentPage := . -}}
|
||||
{{ range .Site.Menus.main -}}
|
||||
<li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
|
||||
<a href="{{ .URL | absLangURL }}">{{ .Name }}</a>
|
||||
</li>
|
||||
{{- end }}
|
||||
</ul>
|
||||
{{ or (T .Identifier) .Name | safeHTML }}
|
||||
```
|
||||
|
||||
### Dynamically localizing menus with i18n
|
||||
It queries the translation table for the current language using the menu entry's `identifier` and returns the translated string. If the translation table does not exist, or if the `identifier` key is not present in the translation table, it falls back to `name`.
|
||||
|
||||
While customizing menus per language is useful, your config file can become hard to maintain if you have a lot of languages
|
||||
The `identifier` depends on how you define menu entries:
|
||||
|
||||
If your menus are the same in all languages (ie. if the only thing that changes is the translated name) you can use the `.Identifier` as a translation key for the menu name:
|
||||
- If you define the menu entry [automatically] using the section pages menu, the `identifier` is the page's `.Section`.
|
||||
- If you define the menu entry [in site configuration] or [in front matter], set the `identifier` property to the desired value.
|
||||
|
||||
{{< code-toggle file="config" >}}
|
||||
For example, if you define menu entries in site configuration:
|
||||
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
[[menu.main]]
|
||||
name = "About me"
|
||||
url = "about"
|
||||
identifier = 'products'
|
||||
name = 'Products'
|
||||
pageRef = '/products'
|
||||
weight = 10
|
||||
[[menu.main]]
|
||||
identifier = 'services'
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 20
|
||||
{{< / code-toggle >}}
|
||||
|
||||
Create corresponding entries in the translation tables:
|
||||
|
||||
{{< code-toggle file="i18n/de" copy=false >}}
|
||||
products = 'Produkte'
|
||||
services = 'Leistungen'
|
||||
{{< / code-toggle >}}
|
||||
|
||||
[example menu template]: http://localhost:1313/templates/menu-templates/#example
|
||||
[automatically]: /content-management/menus/#define-automatically
|
||||
[in front matter]: /content-management/menus/#define-in-front-matter
|
||||
[in site configuration]: /content-management/menus/#define-in-site-configuration
|
||||
|
||||
### Create language-specific menu entries
|
||||
|
||||
For example:
|
||||
|
||||
{{< code-toggle file="config" copy=false >}}
|
||||
[languages.de]
|
||||
languageCode = 'de-DE'
|
||||
languageName = 'Deutsch'
|
||||
weight = 1
|
||||
identifier = "about"
|
||||
|
||||
[[languages.de.menu.main]]
|
||||
name = 'Produkte'
|
||||
pageRef = '/products'
|
||||
weight = 10
|
||||
|
||||
[[languages.de.menu.main]]
|
||||
name = 'Leistungen'
|
||||
pageRef = '/services'
|
||||
weight = 20
|
||||
|
||||
[languages.en]
|
||||
languageCode = 'en-US'
|
||||
languageName = 'English'
|
||||
weight = 2
|
||||
|
||||
[[languages.en.menu.main]]
|
||||
name = 'Products'
|
||||
pageRef = '/products'
|
||||
weight = 10
|
||||
|
||||
[[languages.en.menu.main]]
|
||||
name = 'Services'
|
||||
pageRef = '/services'
|
||||
weight = 20
|
||||
{{< /code-toggle >}}
|
||||
|
||||
You now need to specify the translations for the menu keys in the i18n files:
|
||||
|
||||
{{< code file="i18n/pt.toml" >}}
|
||||
[about]
|
||||
other="Sobre mim"
|
||||
{{< /code >}}
|
||||
|
||||
And do the appropriate changes in the menu code to use the `i18n` tag with the `.Identifier` as a key. You will also note that here we are using a `default` to fall back to `.Name`, in case the `.Identifier` key is also not present in the language specified in the `defaultContentLanguage` configuration.
|
||||
|
||||
{{< code file="layouts/partials/menu.html" >}}
|
||||
<ul>
|
||||
{{- $currentPage := . -}}
|
||||
{{ range .Site.Menus.main -}}
|
||||
<li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
|
||||
<a href="{{ .URL | absLangURL }}">{{ i18n .Identifier | default .Name}}</a>
|
||||
</li>
|
||||
{{- end }}
|
||||
</ul>
|
||||
{{< /code >}}
|
||||
For a simple menu with two languages, these menu entries are easy to create and maintain. For a larger menu, or with more than two languages, using translation tables as described above is preferable.
|
||||
|
||||
## Missing Translations
|
||||
|
||||
|
||||
@@ -1,183 +1,127 @@
|
||||
---
|
||||
title: Menu Templates
|
||||
linktitle: Menu Templates
|
||||
description: Menus are a powerful but simple feature for content management but can be easily manipulated in your templates to meet your design needs.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
linkTitle: Menu Templates
|
||||
description: Use menu variables and methods in your templates to render a menu.
|
||||
categories: [templates]
|
||||
keywords: [lists,sections,menus]
|
||||
menu:
|
||||
docs:
|
||||
title: "how to use menus in templates"
|
||||
parent: "templates"
|
||||
weight: 130
|
||||
toc: true
|
||||
weight: 130
|
||||
sections_weight: 130
|
||||
draft: false
|
||||
aliases: [/templates/menus/]
|
||||
toc: false
|
||||
---
|
||||
|
||||
Hugo makes no assumptions about how your rendered HTML will be
|
||||
structured. Instead, it provides all the functions you will need to
|
||||
build your menu however you want.
|
||||
## Overview
|
||||
|
||||
The following is an example:
|
||||
After [defining menu entries], use [menu variables and methods] to render a menu.
|
||||
|
||||
{{< code file="layouts/partials/sidebar.html" download="sidebar.html" >}}
|
||||
<!-- sidebar start -->
|
||||
<aside>
|
||||
Three factors determine how to render a menu:
|
||||
|
||||
1. The method used to define the menu entries: [automatic], [in front matter]. or [in site configuration]
|
||||
1. The menu structure: flat or nested
|
||||
1. The method used to [localize the menu entries]: site configuration or translation tables
|
||||
|
||||
The example below handles every combination.
|
||||
|
||||
## Example
|
||||
|
||||
This partial template recursively "walks" a menu structure, rendering a localized, accessible nested list.
|
||||
|
||||
{{< code file="layouts/partials/menu.html" >}}
|
||||
{{- $page := .page }}
|
||||
{{- $menuID := .menuID }}
|
||||
|
||||
{{- with index site.Menus $menuID }}
|
||||
<nav>
|
||||
<ul>
|
||||
{{ $currentPage := . }}
|
||||
{{ range .Site.Menus.main }}
|
||||
{{ if .HasChildren }}
|
||||
<li class="{{ if $currentPage.HasMenuCurrent "main" . }}active{{ end }}">
|
||||
<a href="#">
|
||||
{{ .Pre }}
|
||||
<span>{{ .Name }}</span>
|
||||
</a>
|
||||
</li>
|
||||
<ul class="sub-menu">
|
||||
{{ range .Children }}
|
||||
<li class="{{ if $currentPage.IsMenuCurrent "main" . }}active{{ end }}">
|
||||
<a href="{{ .URL }}">{{ .Name }}</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ else }}
|
||||
<li>
|
||||
<a href="{{ .URL }}">
|
||||
{{ .Pre }}
|
||||
<span>{{ .Name }}</span>
|
||||
</a>
|
||||
</li>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
<li>
|
||||
<a href="#" target="_blank">Hardcoded Link 1</a>
|
||||
</li>
|
||||
<li>
|
||||
<a href="#" target="_blank">Hardcoded Link 2</a>
|
||||
</li>
|
||||
{{- partial "inline/menu/walk.html" (dict "page" $page "menuEntries" .) }}
|
||||
</ul>
|
||||
</aside>
|
||||
</nav>
|
||||
{{- end }}
|
||||
|
||||
{{- define "partials/inline/menu/walk.html" }}
|
||||
{{- $page := .page }}
|
||||
{{- range .menuEntries }}
|
||||
{{- $attrs := dict "href" .URL}}
|
||||
{{- if $page.IsMenuCurrent .Menu . }}
|
||||
{{- $attrs = merge $attrs (dict "class" "active" "aria-current" "page") }}
|
||||
{{- else if $page.HasMenuCurrent "main" .}}
|
||||
{{- $attrs = merge $attrs (dict "class" "ancestor" "aria-current" "true") }}
|
||||
{{- end }}
|
||||
<li>
|
||||
<a
|
||||
{{- range $k, $v := $attrs }}
|
||||
{{- with $v }}
|
||||
{{- printf " %s=%q" $k $v | safeHTMLAttr }}
|
||||
{{- end }}
|
||||
{{- end -}}
|
||||
>{{ or (T .Identifier) .Name | safeHTML }}</a>
|
||||
{{- with .Children }}
|
||||
<ul>
|
||||
{{- partial "inline/menu/walk.html" (dict "page" $page "menuEntries" .) }}
|
||||
</ul>
|
||||
{{- end }}
|
||||
</li>
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note "`absLangURL` and `relLangURL`" %}}
|
||||
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.
|
||||
{{% /note %}}
|
||||
Call the partial above, passing a menu ID and the current page in context.
|
||||
|
||||
## Section Menu for Lazy Bloggers
|
||||
{{< code file="layouts/_default/single.html" >}}
|
||||
{{ partial "menu.html" (dict "menuID" "main" "page" .) }}
|
||||
{{ partial "menu.html" (dict "menuID" "footer" "page" .) }}
|
||||
{{< /code >}}
|
||||
|
||||
To enable this menu, configure `sectionPagesMenu` in your site `config`:
|
||||
## Page references
|
||||
|
||||
```yml
|
||||
sectionPagesMenu = "main"
|
||||
```
|
||||
Regardless of how you [define menu entries], an entry associated with a page has access to page variables and methods.
|
||||
|
||||
The menu name can be anything, but take a note of what it is.
|
||||
This simplistic example renders a page parameter named `version` next to each entry's `name`. Code defensively using `with` or `if` to handle entries where (a) the entry points to an external resource, or (b) the `version` parameter is not defined.
|
||||
|
||||
This will create a menu with all the sections as menu items and all the sections' pages as "shadow-members". Ensure that all first level directories that you would like to show up on this menu are [Branch Bundles](https://gohugo.io/content-management/sections/). Leaf Bundles do not form sections.
|
||||
{{< code file="layouts/_default/single.html" >}}
|
||||
{{- range site.Menus.main }}
|
||||
<a href="{{ .URL }}">
|
||||
{{ .Name }}
|
||||
{{- with .Page }}
|
||||
{{- with .Params.version -}}
|
||||
({{ . }})
|
||||
{{- end }}
|
||||
{{- end }}
|
||||
</a>
|
||||
{{- end }}
|
||||
{{< /code >}}
|
||||
|
||||
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:
|
||||
## Menu entry parameters
|
||||
|
||||
```go-html-template
|
||||
<nav class="sidebar-nav">
|
||||
{{ $currentPage := . }}
|
||||
{{ range .Site.Menus.main }}
|
||||
<a class="sidebar-nav-item{{if or ($currentPage.IsMenuCurrent "main" .) ($currentPage.HasMenuCurrent "main" .) }} active{{end}}" href="{{ .URL }}" title="{{ .Title }}">{{ .Name }}</a>
|
||||
{{ end }}
|
||||
</nav>
|
||||
```
|
||||
When you define menu entries [in site configuration] or [in front matter], you can include a `params` key as shown in these examples:
|
||||
|
||||
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.
|
||||
- [Menu entry defined in site configuration]
|
||||
- [Menu entry defined in front matter]
|
||||
|
||||
## Site Config menus
|
||||
This simplistic example renders a `class` attribute for each anchor element. Code defensively using `with` or `if` to handle entries where `params.class` is not defined.
|
||||
|
||||
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:
|
||||
{{< code file="layouts/partials/menu.html" >}}
|
||||
{{- range site.Menus.main }}
|
||||
<a {{ with .Params.class -}} class="{{ . }}" {{ end -}} href="{{ .URL }}">
|
||||
{{ .Name }}
|
||||
</a>
|
||||
{{- end }}
|
||||
{{< /code >}}
|
||||
|
||||
{{< code-toggle file="config" >}}
|
||||
[[menu.main]]
|
||||
name = "This is the blog section"
|
||||
title = "blog section"
|
||||
weight = -110
|
||||
identifier = "blog"
|
||||
url = "/blog/"
|
||||
{{</ code-toggle >}}
|
||||
## Localize
|
||||
|
||||
{{% note %}}
|
||||
The `identifier` *must* match the section name.
|
||||
{{% /note %}}
|
||||
Hugo provides two methods to localize your menu entries. See [multilingual].
|
||||
|
||||
## Menu Entries from the Page's front matter
|
||||
|
||||
It's also possible to create menu entries from the page (i.e. the `.md`-file).
|
||||
|
||||
Here is a `yaml` example:
|
||||
|
||||
```yml
|
||||
---
|
||||
title: Menu Templates
|
||||
linktitle: Menu Templates
|
||||
menu:
|
||||
docs:
|
||||
title: "how to use menus in templates"
|
||||
parent: "templates"
|
||||
weight: 130
|
||||
---
|
||||
...
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
You can define more than one menu. It also doesn't have to be a complex value,
|
||||
`menu` can also be a string, an array of strings, or an array of complex values
|
||||
like in the example above.
|
||||
{{% /note %}}
|
||||
|
||||
### Using .Page in Menus
|
||||
|
||||
If you use the front matter method of defining menu entries, you'll get access to the `.Page` variable.
|
||||
This allows to use every variable that's reachable from the [page variable](/variables/page/).
|
||||
|
||||
This variable is only set when the menu entry is defined in the page's front matter.
|
||||
Menu entries from the site config don't know anything about `.Page`.
|
||||
|
||||
That's why you have to use the go template's `with` keyword or something similar in your templating language.
|
||||
|
||||
Here's an example:
|
||||
|
||||
```go-html-template
|
||||
<nav class="sidebar-nav">
|
||||
{{ range .Site.Menus.main }}
|
||||
<a href="{{ .URL }}" title="{{ .Title }}">
|
||||
{{- .Name -}}
|
||||
{{- with .Page -}}
|
||||
<span class="date">
|
||||
{{- dateFormat " (2006-01-02)" .Date -}}
|
||||
</span>
|
||||
{{- end -}}
|
||||
</a>
|
||||
{{ end }}
|
||||
</nav>
|
||||
```
|
||||
|
||||
## Using .Params in Menus
|
||||
|
||||
User-defined content on menu items are accessible via `.Params`.
|
||||
|
||||
Here's an example:
|
||||
|
||||
```go-html-template
|
||||
<nav class="sidebar-nav">
|
||||
{{ range .Site.Menus.main }}
|
||||
<a href="{{ .URL }}" title="{{ .Title }}" class="{{ with .Params.class }}{{ . }}{{ end }}">
|
||||
{{- .Name -}}
|
||||
</a>
|
||||
{{ end }}
|
||||
</nav>
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
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).
|
||||
{{% /note %}}
|
||||
[automatic]: /content-management/menus/#define-automatically
|
||||
[define menu entries]: /content-management/menus/
|
||||
[defining menu entries]: /content-management/menus/
|
||||
[in front matter]: /content-management/menus/#define-in-front-matter
|
||||
[in site configuration]: /content-management/menus/#define-in-site-configuration
|
||||
[localize the menu entries]: /content-management/multilingual/#menus
|
||||
[Menu entry defined in front matter]: /content-management/menus/#example-front-matter
|
||||
[Menu entry defined in site configuration]: /content-management/menus/#example-site-configuration
|
||||
[menu variables and methods]: /variables/menus/
|
||||
[multilingual]: /content-management/multilingual/#menus
|
||||
|
||||
+68
-101
@@ -1,127 +1,94 @@
|
||||
---
|
||||
title: Menu Entry Properties
|
||||
linktitle: Menu Entry Properties
|
||||
description: A menu entry in a menu-template has specific variables and functions to make menu management easier.
|
||||
date: 2017-03-12
|
||||
publishdate: 2017-03-12
|
||||
lastmod: 2017-03-12
|
||||
title: Menu Variables
|
||||
linktitle: Menu Variables
|
||||
description: Use these variables and methods in your menu templates.
|
||||
categories: [variables and params]
|
||||
keywords: [menus]
|
||||
draft: false
|
||||
menu:
|
||||
docs:
|
||||
title: "variables defined by a menu entry"
|
||||
parent: "variables"
|
||||
weight: 50
|
||||
weight: 50
|
||||
sections_weight: 50
|
||||
aliases: [/variables/menu/]
|
||||
toc: false
|
||||
weight: 50
|
||||
aliases: [/variables/menu/]
|
||||
---
|
||||
|
||||
A **menu entry** has the following properties available that can be used in a
|
||||
[menu template][menu-template].
|
||||
## Variables
|
||||
|
||||
## Menu Entry Variables
|
||||
|
||||
.Menu
|
||||
: _string_ <br />
|
||||
Name of the **menu** that contains this **menu entry**.
|
||||
|
||||
.URL
|
||||
: _string_ <br />
|
||||
URL that the menu entry points to. The `url` key, if set for the menu entry,
|
||||
sets this value. If that key is not set, and if the menu entry is set in a page
|
||||
front-matter, this value defaults to the page's `.RelPermalink`.
|
||||
|
||||
.Page
|
||||
: _\*Page_ <br />
|
||||
Reference to the [page object][page-object] associated with the menu entry. This
|
||||
will be non-nil if the menu entry is set via a page's front-matter and not via
|
||||
the site config.
|
||||
|
||||
.PageRef
|
||||
: _string_ <br /> Can be set if defined in site config and the menu entry refers to a Page. [site.GetPage](/functions/getpage/) will be used to do the page lookup. If this is set, you don't need to set the `URL`.
|
||||
|
||||
.Name
|
||||
: _string_ <br />
|
||||
Name of the menu entry. The `name` key, if set for the menu entry, sets
|
||||
this value. If that key is not set, and if the menu entry is set in a page
|
||||
front-matter, this value defaults to the page's `.LinkTitle`.
|
||||
|
||||
.Identifier
|
||||
: _string_ <br />
|
||||
Value of the `identifier` key if set for the menu entry. This value must be
|
||||
unique for each menu entry. **It is necessary to set a unique identifier
|
||||
manually if two or more menu entries have the same `.Name`.**
|
||||
|
||||
.Pre
|
||||
: _template.HTML_ <br />
|
||||
Value of the `pre` key if set for the menu entry. This value typically contains
|
||||
a string representing HTML.
|
||||
|
||||
.Post
|
||||
: _template.HTML_ <br />
|
||||
Value of the `post` key if set for the menu entry. This value typically contains
|
||||
a string representing HTML.
|
||||
|
||||
.Weight
|
||||
: _int_ <br />
|
||||
Value of the `weight` key if set for the menu entry. By default the entries in
|
||||
a menu are sorted ascending by their `weight`. If that key is not set, and if
|
||||
the menu entry is set in a page front-matter, this value defaults to the page's
|
||||
`.Weight`.
|
||||
|
||||
.Parent
|
||||
: _string_ <br />
|
||||
Name (or Identifier if present) of this menu entry's parent **menu entry**. The
|
||||
`parent` key, if set for the menu entry, sets this value. If this key is set,
|
||||
this menu entry nests under that parent entry, else it nests directly under the
|
||||
`.Menu`.
|
||||
After [defining the menu entries], access their properties with these variables.
|
||||
|
||||
.Children
|
||||
: _Menu_ <br />
|
||||
This value is auto-populated by Hugo. It is a collection of children menu
|
||||
entries, if any, under the current menu entry.
|
||||
: (menu) A collection of child menu entries, if any, under the current menu entry.
|
||||
|
||||
## Menu Entry Functions
|
||||
|
||||
Menus also have the following functions available:
|
||||
|
||||
.HasChildren
|
||||
: _boolean_ <br />
|
||||
Returns `true` if `.Children` is non-nil.
|
||||
.Identifier
|
||||
: (string) The `identifier` property of the menu entry. If you define the menu entry [automatically], the page's `.Section`.
|
||||
|
||||
.KeyName
|
||||
: _string_ <br />
|
||||
Returns the `.Identifier` if present, else returns the `.Name`.
|
||||
: (string) The `identifier` property of the menu entry, else the `name` property.
|
||||
|
||||
.IsEqual
|
||||
: _boolean_ <br />
|
||||
Returns `true` if the two compared menu entries represent the same menu entry.
|
||||
.Menu
|
||||
: (string) The identifier of the menu that contains the menu entry.
|
||||
|
||||
.IsSameResource
|
||||
: _boolean_ <br />
|
||||
Returns `true` if the two compared menu entries have the same `.URL`.
|
||||
.Name
|
||||
: (string) The `name` property of the menu entry.
|
||||
|
||||
- If you define the menu entry [automatically], the page's `.LinkTitle`, else the page's `.Title`.
|
||||
- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.LinkTitle`, then to the page's `.Title`.
|
||||
|
||||
.Page
|
||||
: (page) A reference to the page associated with the menu entry.
|
||||
|
||||
<!-- This provides no value when rendering menu. Omitting to avoid confusion.
|
||||
.PageRef
|
||||
: (string) The `pageRef` property of the menu entry.
|
||||
-->
|
||||
|
||||
.Params
|
||||
: (map) The `params` property of the menu entry.
|
||||
|
||||
.Parent
|
||||
: (string) The `parent` property of the menu entry.
|
||||
|
||||
.Post
|
||||
: (template.HTML) The `post` property of the menu entry.
|
||||
|
||||
.Pre
|
||||
: (template.HTML) The `pre` property of the menu entry.
|
||||
|
||||
.Title
|
||||
: _string_ <br />
|
||||
Link title, meant to be used in the `title` attribute of a menu entry's
|
||||
`<a>`-tags. Returns the menu entry's `title` key if set. Else, if the menu
|
||||
entry was created through a page's front-matter, it returns the page's
|
||||
`.LinkTitle`. Else, it just returns an empty string.
|
||||
: (string) The `title` property of the menu entry.
|
||||
|
||||
## Other Menu-related Functions
|
||||
- If you define the menu entry [automatically], the page's `.LinkTitle`, else the page's `.Title`.
|
||||
- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.LinkTitle`, then to the page's `.Title`.
|
||||
|
||||
Additionally, here are some relevant methods available to menus on a page:
|
||||
.URL
|
||||
: (string) The `.RelPermalink` of the page associated with the menu entry. For menu entries pointing to external resources, the `url` property of the menu entry.
|
||||
|
||||
.IsMenuCurrent
|
||||
: _(menu string, menuEntry *MenuEntry ) boolean_ <br />
|
||||
See [`.IsMenuCurrent` method](/functions/ismenucurrent/).
|
||||
.Weight
|
||||
: (int) The `weight` property of the menu entry.
|
||||
|
||||
.HasMenuCurrent
|
||||
: _(menu string, menuEntry *MenuEntry) boolean_ <br />
|
||||
See [`.HasMenuCurrent` method](/functions/hasmenucurrent/).
|
||||
- If you define the menu entry [automatically], the page's `.Weight`.
|
||||
- If you define the menu [in front matter] or [in site configuration], falls back to the page's `.Weight`.
|
||||
|
||||
[menu-template]: /templates/menu-templates/
|
||||
[page-object]: /variables/page/
|
||||
## Methods
|
||||
|
||||
.HasChildren
|
||||
: (bool) Returns `true` if `.Children` is non-nil.
|
||||
|
||||
.IsEqual
|
||||
: (bool) Returns `true` if the compared menu entries represent the same menu entry.
|
||||
|
||||
.IsSameResource
|
||||
: (bool) Returns `true` if the compared menu entries point to the same resource.
|
||||
|
||||
.Page.HasMenuCurrent
|
||||
: (bool) Use this method to determine ancestors of the active menu entry. See [details](/functions/hasmenucurrent/).
|
||||
|
||||
.Page.IsMenuCurrent
|
||||
: (bool) Use this method to determine the active menu entry. See [details](/functions/ismenucurrent/).
|
||||
|
||||
[automatically]: /content-management/menus/#define-automatically
|
||||
[defining the menu entries]: /content-management/menus/#overview
|
||||
[in front matter]: /content-management/menus/#define-in-front-matter
|
||||
[in site configuration]: /content-management/menus/#define-in-site-configuration
|
||||
|
||||
Reference in New Issue
Block a user