11tyThe possum is Eleventy’s mascot

Eleventy Documentation

Menu

Navigation Plugin #

A plugin for creating hierarchical navigation in Eleventy projects. Supports breadcrumbs too! Used in production on this very website!

Template Compatibility #

Installation #

Available on npm.

npm install @11ty/eleventy-navigation --save-dev

Open up your Eleventy config file (probably .eleventy.js) and use addPlugin:

Filename .eleventy.js
const eleventyNavigationPlugin = require("@11ty/eleventy-navigation");
module.exports = function(eleventyConfig) {
eleventyConfig.addPlugin(eleventyNavigationPlugin);
};

Adding Templates to the Navigation #

Add the eleventyNavigation object to your front matter data (or in a data directory file). Assign a unique string to the key property inside of eleventyNavigation:

mammals.md: #

---
eleventyNavigation:
key: Mammals
---

This gives us:

humans.md #

To nest a template inside of the Mammals template, use parent: Mammals:

---
eleventyNavigation:
key: Humans
parent: Mammals
---

Any templates that do not have parent will be assumed to be at the top level.

Now our navigation structure looks like:

bats.md #

---
eleventyNavigation:
key: Bats
parent: Mammals
---

Now our navigation structure looks like:

You can nest these as deep as you want! Want to put something under Humans or Bats? Use parent: Humans or parent: Bats. If you want to add another root template, leave out parent.

If you want your key and your link text to be different, use the title property:

---
eleventyNavigation:
key: Mammals
title: All of the Mammals
---

Re-ordering Items #

To ensure that Humans comes first before Bats, use the order property. It can have an arbitrary number. If omitted, order: 0 is the default.

---
eleventyNavigation:
key: Humans
parent: Mammals
order: 1
---
---
eleventyNavigation:
key: Bats
parent: Mammals
order: 2
---

Rendering the Navigation Bar (Nunjucks) #

Currently only Nunjucks support is available for this plugin. More to come!

Full Navigation Tree #

{{ collections.all | eleventyNavigation | eleventyNavigationToHtml | safe }}

Just one Branch #

Just show the children of a specific key, passing a key to eleventyNavigation:

{{ collections.all | eleventyNavigation("Humans") | eleventyNavigationToHtml | safe }}

You can also render only the parents of a specific key too, to make breadcrumb navigation. Pass a key to eleventyNavigationBreadcrumb like this:

{{ collections.all | eleventyNavigationBreadcrumb("Bats") | eleventyNavigationToHtml | safe }}

Showing excerpts #

You can also use this to display a longer list of navigation items with description text. Add excerpt to the eleventyNavigation object.

---
eleventyNavigation:
key: Mammals
excerpt: Vertebrate animals of the class Mammalia.
---

When you render a navigation list, pass showExcerpt: true to the eleventyNavigationToHtml filter, like so:

{{ collections.all | eleventyNavigation("Humans") | eleventyNavigationToHtml({ showExcerpt: true }) | safe }}

Advanced Rendering Options for eleventyNavigationToHtml #

You can change the HTML elements, classes on the list and list items, and add an additional class for the current page’s navigation entry!

{{ collections.all | eleventyNavigation | eleventyNavigationToHtml({
    listElement: "ul",            // Change the top level tag
    listItemElement: "li",        // Change the item tag

    listClass: "",                // Add a class to the top level
    listItemClass: "",            // Add a class to every item
    listItemHasChildrenClass: "", // Add a class if the item has children
    activeListItemClass: "",      // Add a class to the current page’s item

    // If matched, `activeListItemClass` will be added to the item
    activeKey: "",
    // It’s likely you want to pass in `eleventyNavigation.key` here, e.g.:
    // activeKey: eleventyNavigation.key

    // Show excerpts (if they exist in data, read more above)
    showExcerpt: false
}) | safe }}

These work with eleventyNavigationBreadcrumb | eleventyNavigationToHtml too.

If you need even more power than this filter provides, you can look at the JSON structure returned from eleventyNavigation and eleventyNavigationBreadcrumb and write your own filter to output HTML!