How to create data-driven navigation in Jekyll

When you need to iterate quickly, a data-driven structure can slash development time. Here's how to get started with Jekyll's new data files.

In the early stage of a web project when I’m still prototyping – whether it’s an ecommerce site or a marketing microsite —- I often have a need to iterate quickly, making changes on the fly as the project is tweaked to fit the needs of my client. In an agile environment, things move fast indeed. A framework such as Twitter Bootstrap helps get things done quickly, and lately I’ve also added Jekyll to the mix.

Jekyll, for the uninitiated, is a static website generator. With it, you can quickly compile and preview your work without having to set up and configure a full CMS (you can always convert the static markup for use with your CMS of choice later).

For a recent project, I had a need to implement a nested navigation system but with the navigation not yet final, I wanted to be able to make rapid changes without toying with the underlying HTML markup. To do this, I turned to Jekyll’s new “data files” feature. Since I wasn’t able to find a tutorial online on how to use nested navigation and Jekyll’s data files, I dove in and wrote this brief explanation myself.

Create your data file in YAML

The data files feature of Jekyll is still fairly new. It allows you to specify your own custom structured data that can be accessed via the Liquid templating system. The basic idea is to use data files to avoid copy and pasting large chunks of code in your Jekyll templates.

For my project, I wanted to have a nested navigation system that was driven by a data file, so this meant setting up a nested list structure in YAML, the default language for Jekyll’s config and data files (you can also use JSON, but I stuck to YAML for this project). Be forewarned: YAML can be finicky if you don’t watch your whitespace. After some trial and error, I found the optimal YML structure for my project:

Note the indented nested list using a hyphen character.

Copy that code to your _data directory in your Jekyll project and name it nav.yml (create the directory if you need to). Be careful not to replace the spaces in your data file with tabs or Jekyll will complain about “mapping values” when you try to compile your site.

Calling your data

Now that your data file is in place, you can access it via Liquid. To do this, we need to do a few things:

  • Call the data file from your navigation template code
  • Loop over the data so that your navigation is displayed as separate items in a list
  • Create logic that displays a sub-menu only when it’s needed

Like other technologies, there’s no one way to do things in Jekyll. Here’s how I performed the above tasks.

A quick house-keeping note: If you haven’t already done so, put your navigation code into a fragment and copy it to your _include directory. This makes editing cleaner. Then reference the include from your default.html layout file.

Create a FOR loop

In your navigation file, initiate a FOR loop like so:

You can/should replace the variable “dale” with whatever you want.

Is there a sub-menu?

Now, check to see if your data file contains a sub-menu item, and if so display it:

So, what this statement says in plain English is “Okay, look in the data file at each navigation item. If there’s a submenu there called subcategories, display it. If not, keep calm, skip the markup code below and move on to the HTML code after the ELSE statement”.

Display the sub-menu

Now, let’s write our HTML display markup code for navigation items that have a sub-menu:

This markup tells the Bootstrap template to display a little arrow icon next to the menu, telling the user that there’s a sub-menu that you can mouse over.

Then, we tell our template code to display the actual sub-menu. To do this, we use another FOR loop:

This code tells Jekyll to display each sub-menu item one by one in a list. It pulls the menu name from the data file as well as its hyperlink. Pretty easy stuff.

Display the top-level menu

The rest of your template code is for displaying top-level navigation items that do not have a sub-menu.

Here’s what the entire nav template code looks like:

All together now

By using this data-driven method, I can very quickly change the website’s navigation using structured data in the YML file. It’s not hard to just statically edit the site’s navigation in basic HTML, but learning to use the time-saving features of Jekyll is a good habit that can shave time off your project.

POSTSCRIPT: I'm working on adding top-level nav highlighting for active pages.