Site menus and their menu items can be defined in two ways:

  • Global menu items - defined by menus field inside config.yml
  • Page menu items - defined by menus field inside page front matter

    Global Menu Items

Global menu items are defined inside config.yaml as a list of objects belonging to a specific menu, identified by named key inside the root menus field.

  • identifier - can be used to create nested menus
  • title - title of the menu item. Required
  • url - target url of the menu item. Required
  • weight - specified the position of the menu item among other menu items in the same menu. Lower values position menu items at lower indexes (lower indexes come first).
# config.yaml

menus:
  main: # the name of the menu, this can be anything
    - identifier: login
      title: Login
      url: /login
      weight: 1
    - identifier: signup
      title: Signup
      url: /signup
      weight: 2
    - identifier: submenu
      title: Menu
      url: "#"
      weight: 3
  submenu: # another menu, you can access it a layout using site.menus.submenu
    - title: About
      url: about.html
      weight: 1
    - title: Contact
      url: /contact
      weight: 2

Page Menu Items

Page menu items are defined inside content's front matter.

  • title - title of the menu item. Required
  • weight - specified the position of the menu item among other menu items in the same menu. Lower values position menu items at lower indexes (lower indexes come first).
# content/portfolio.md

---
title: Portfolio
template: page
menus:
  main: # the menus name, which can be accessed via {{ site.menus.main }}
    title: Portfolio
    weight: 3
---

Lorem Ipsum

Using Menus in Layouts

Menus can be accessed through site.menus object. This object references root menus through their name (e.g.: site.menus.main).

Menus can be accessed in Layouts and Components

Every menu is an array of menu item objects sorted by their weight, having the following fields:

  • menu: the name (or identifier) of the menu this menu item belong to
  • title: the menu item title
  • url: the target url of the menu item
  • weight: the weight of menu item
  • page: the reference to the page object this menu item relates to (will be null for global menu items)
  • identifier: the identifier of this menu item

Example menu in a layout

<!-- components/home.html -->

<ul>
{% for item in site.menus.main %}
    <li {% if item.url == page.url %}class="active"{% endif %}>
        <a href="{{ item.url }}">{{ item.title }}</a>
    </li>
{% endfor %}
</ul>