Navigation Menus

Mark up your navigation menus using any HTML structure that you wish.

Live Editor provides a navigation object that allows you to loop through a navigation menu tree and mark up the interface however you require.

Within your theme’s directory structure is a folder called navigation, which will look something like this:

• ...
• navigation
  • global_navigation.liquid
  • navigation.json
• ...

Let’s take a look at each type of file.

The navigation.json config file

The navigation.json file is in JSON format and allows you to list and configure 1 or more navigation menus.

Here is an example navigation.json file:

      {
        "navigation": [
          {
            "title": "Global",
            "description": "Main menu for entire site."
          }
        ]
      }

The following options are available for each menu listed in navigation.json:

Once you add a navigation menu to navigation.json, it will appear for editing in the Live Editor admin under Design > Navigation.

Navigation menus are optional in Live Editor, so you can safely remove the navigation folder from your theme if you don’t plan on having any.

Templating navigation menus using Liquid markup

Once you have at least one navigation menu configured, you can move on to its Liquid template.

By default, if your navigation menu is titled “Global,” it will have a corresponding Liquid template file at global_navigation.liquid.

Within the Liquid file, you will have access to an object named navigation. This object will contain a tree of links that are editable in the Live Editor admin interface. If you are in globl_navigation.liquid (per our example), the navigation object will load data from the navigation menu titled “Global.”

The navigation.links attribute will contain an array of zero or more link objects that you can loop through and output:

      <nav class="global-nav">
        {% for link in navigation.links %}
          <a href="{{ link.url }}" class="global-nav-link {% if link.active? %}is-active{% endif %}">
            {{ link.title }}
          </a>
        {% endfor %}
      </nav>

As you can see, the link object has a few attributes that you can work with, including url, title, and active.

Including navigation menus in layouts

To include a navigation menu in a layout, use the navigation tag with the var_name of the navigation menu as its first argument:

      <header>
        {% navigation 'global' %}
      </header>

Displaying a nested tree of navigation links

Another useful attribute within link is children, which returns an array of child links in the navigation menu tree.

To display a nested tree of links, you could code something like this:

      <ul>
        {% for link in navigation.links %}
          {% include 'global_navigation_items' %}
        {% endfor %}
      </ul>

The usage of the include tag allows you to create a file in the theme at partials/global_navigation_items.liquid that will be included recursively and run in its place:

      <li>
        <a href="{{ link.url }}">{{ link.title }}</a>
      
        {% if link.children.size > 0 %}
          <ul>
            {% for link in link.children %}
              {% include 'global_navigation_items' %}
            {% endfor %}
          </ul>
        {% endif %}
      </li>

(Hat tip to Pixel Union for this tip.)

Limiting the depth of the nested tree

If you are in danger of bogging down your page with too many levels of depth of your navigation menu (going beyond 2 or 3 levels may not be practical in your interface), you can use the limit_depth argument of the navigation tag:

{% navigation 'Global', limit_depth: 2 %}

With the limit_depth argument in place, Live Editor will only load children up to a limited number of levels deep (in the example above, 2).

Next steps

Define the how content should be structured and displayed by reading our Content Templates guide.