github.com/lyeb/hugo@v0.47.1/docs/content/en/templates/menu-templates.md (about)

     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  ```