hugo/docs/content/en/templates/menu-templates.md
2023-10-20 09:43:56 +02:00

4.2 KiB

title description categories keywords menu toc weight aliases
Menu templates Use menu variables and methods in your templates to render a menu.
templates
lists
sections
menus
docs
parent weight
templates 140
true 140
/templates/menus/

Overview

After defining menu entries, use menu variables and methods to render a menu.

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
  2. The menu structure: flat or nested
  3. 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 }}

    {{- partial "inline/menu/walk.html" (dict "page" $page "menuEntries" .) }}
{{- 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 .Menu .}} {{- $attrs = merge $attrs (dict "class" "ancestor" "aria-current" "true") }} {{- end }} {{- $name := .Name }} {{- with .Identifier }} {{- with T . }} {{- $name = . }} {{- end }} {{- end }}

  • <a {{- range $k, $v := $attrs }} {{- with $v }} {{- printf " %s=%q" $k $v | safeHTMLAttr }} {{- end }} {{- end -}} >{{ $name }} {{- with .Children }}
      {{- partial "inline/menu/walk.html" (dict "page" $page "menuEntries" .) }}
    {{- end }}
  • {{- end }} {{- end }} {{< /code >}}

    Call the partial above, passing a menu ID and the current page in context.

    {{< code file="layouts/_default/single.html" >}} {{ partial "menu.html" (dict "menuID" "main" "page" .) }} {{ partial "menu.html" (dict "menuID" "footer" "page" .) }} {{< /code >}}

    Page references

    Regardless of how you define menu entries, an entry associated with a page has access to page variables and methods.

    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.

    {{< code file="layouts/_default/single.html" >}} {{- range site.Menus.main }} {{ .Name }} {{- with .Page }} {{- with .Params.version -}} ({{ . }}) {{- end }} {{- end }} {{- end }} {{< /code >}}

    Menu entry parameters

    When you define menu entries in site configuration or in front matter, you can include a params key as shown in these examples:

    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.

    {{< code file="layouts/partials/menu.html" >}} {{- range site.Menus.main }} <a {{ with .Params.class -}} class="{{ . }}" {{ end -}} href="{{ .URL }}"> {{ .Name }} {{- end }} {{< /code >}}

    Localize

    Hugo provides two methods to localize your menu entries. See multilingual.