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:

Option Required Description
title Yes string Title of menu.
var_name No string This will be used to reference this navigation menu within a navigation tag in a layout or content template display. If not provided, var_name defaults to the value of title, all lowercase and underscored (e.g., if the title is “Executive Team,” the default value to use within the code would be executive_team).
description No string Description of menu that will appear for content authors in the Live Editor admin.
file_name No string Name of .liquid file to reference in the navigation folder for display.

This defaults to the value of var_name, followed by _navigation.liquid. (For example, if the title is “Global,” then the default for file_name will be global_navigation.liquid.)

The file_name must have a .liquid extension.

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:

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

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:

        {% navigation 'global' %}

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:

Example navigation/global_navigation.liquid
        {% for link in navigation.links %}
          {% include 'global_navigation_items' %}
        {% endfor %}

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:

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

(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.