Navigation

Stable: 3.0.0
Canary: 3.0.1-alpha.1

Toggle Menu

Compare npm install

Eleventy 5.81s

Remix 40.14s

Contents

Template Compatibility
Installation
Adding Templates to the Navigation
Rendering the Navigation Menu (Easy Mode)
- Output HTML
- To Markdown
Advanced: Rendering the Navigation Bar (Deep Dive)

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

This documentation is for eleventy-navigation v0.3.x.
GitHub.

Template Compatibility

Any template language can add to navigation.
Any template language compatible with Universal Filters can render the navigation menu.

Installation

Available on npm.

npm install @11ty/eleventy-navigation

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

eleventy.config.js

ESM CommonJS

import eleventyNavigationPlugin from "@11ty/eleventy-navigation";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(eleventyNavigationPlugin);
};

const eleventyNavigationPlugin = require("@11ty/eleventy-navigation");

module.exports = function (eleventyConfig) {
	eleventyConfig.addPlugin(eleventyNavigationPlugin);
};

Example

mammals.md

---
eleventyNavigation:
  key: Mammals
---

This gives us:

Mammals

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:

Mammals - Humans

bats.md

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

Now our navigation structure looks like:

Mammals - Humans - Bats

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

Overriding the URL

Added in Navigation v0.1.4 If you’d like to add a link to an external URL that is not on your local page, create a new file for it and add a url key.

---
eleventyNavigation:
  key: Zach’s site
  url: https://www.zachleat.com/
permalink: false
---

Use permalink: false to ensure that this meta-template doesn’t create a file in your Eleventy site output.

Template languages that support universal filters are supported. If you’re tired of reading, just use one of the following. These are using the filters documented below. If you want more control or need additional customization, keep reading!

Output HTML

WebC Liquid Nunjucks 11ty.js 11ty.cjs

Syntax Liquid

{{ collections.all | eleventyNavigation | eleventyNavigationToHtml }}

Syntax Nunjucks

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

Syntax WebC

<nav
	@html="eleventyNavigationToHtml(eleventyNavigation($data.collections.all))"
></nav>

This example has not yet been added—you can swap to another template language above! Or maybe you want to contribute it? Edit this page

To Markdown

Added in Navigation 0.3.1 This is most useful in .md files (preprocessed as Liquid or Nunjucks). It’s highly unlikely you want to output Markdown in a WebC file (but maybe you do, I’m not your parent). You probably want the HTML example above.

WebC Liquid Nunjucks 11ty.js 11ty.cjs

Syntax Liquid

{{ collections.all | eleventyNavigation | eleventyNavigationToMarkdown }}

Syntax Nunjucks

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

Syntax WebC

<nav
	@html="eleventyNavigationToMarkdown(eleventyNavigation($data.collections.all))"
></nav>

This example has not yet been added—you can swap to another template language above! Or maybe you want to contribute it? Edit this page

Fetch the menu items using the `eleventyNavigation` Filter

The eleventyNavigation filter returns a sorted array of objects with url and title properties (sorted using order, as noted above). If an entry has nested children, it will also include a children property with an array of similar objects (and those may contain children too, and so on).

Example: Fetch all pages

For our documented templates above with the following template:

Liquid Nunjucks 11ty.js 11ty.cjs

Syntax Liquid

{% assign navPages = collections.all | eleventyNavigation %}
{{ navPages | json }}

Syntax Nunjucks

{% set navPages = collections.all | eleventyNavigation %}
{{ navPages | dump | safe }}

This example has not yet been added—you can swap to another template language above! Or maybe you want to contribute it? Edit this page

INFO:

Note that you can also pass any collection into eleventyNavigation. It doesn’t have to be collections.all!

Shows that navPages has the following structure:

[
	{
		"key": "Mammals",
		"url": "/mammals/",
		"title": "Mammals",
		"children": [
			{
				"key": "Humans",
				"parentKey": "Mammals",
				"url": "/humans/",
				"title": "Humans"
			},
			{
				"key": "Bats",
				"parentKey": "Mammals",
				"url": "/bats/",
				"title": "Bats"
			}
		]
	}
]

Example: Get just one Branch

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

Liquid Nunjucks 11ty.js 11ty.cjs

Syntax Liquid

{% assign navPages = collections.all | eleventyNavigation: "Mammals" %}
{{ navPages | json }}

Syntax Nunjucks

{% set navPages = collections.all | eleventyNavigation("Mammals") %}
{{ navPages | dump | safe }}

This example has not yet been added—you can swap to another template language above! Or maybe you want to contribute it? Edit this page

[
	{
		"key": "Humans",
		"parentKey": "Mammals",
		"url": "/humans/",
		"title": "Humans"
	},
	{
		"key": "Bats",
		"parentKey": "Mammals",
		"url": "/bats/",
		"title": "Bats"
	}
]

Example: Breadcrumbs

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

Liquid Nunjucks 11ty.js 11ty.cjs

Syntax Liquid

{% assign navPages = collections.all | eleventyNavigationBreadcrumb: "Bats" %}
{{ navPages | json }}

Syntax Nunjucks

{% set navPages = collections.all | eleventyNavigationBreadcrumb("Bats") %}
{{ navPages | dump | safe }}

This example has not yet been added—you can swap to another template language above! Or maybe you want to contribute it? Edit this page

And an array of all the parents of the Bats entry will be returned (top-most parent is first):

[
	{
		"key": "Mammals",
		"url": "/mammals/",
		"title": "Mammals"
	}
]

Liquid Nunjucks 11ty.js 11ty.cjs

Syntax Liquid

---
navOptions:
  includeSelf: true
---
{% assign navPages = collections.all | eleventyNavigationBreadcrumb: "Mammals", navOptions %}
{{ navPages | json }}

Syntax Nunjucks

{% set navPages = collections.all | eleventyNavigationBreadcrumb("Bats", { includeSelf: true }) %}
{{ navPages | dump | safe }}

This example has not yet been added—you can swap to another template language above! Or maybe you want to contribute it? Edit this page

Allow missing pages (nodes) in breadcrumbs

Added in Navigation 0.3.3

Liquid Nunjucks 11ty.js 11ty.cjs

Syntax Liquid

---
navOptions:
  allowMissing: true
---
{% assign navPages = collections.all | eleventyNavigationBreadcrumb: "Does not exist", navOptions %}
{{ navPages | json }}

Syntax Nunjucks

{% set navPages = collections.all | eleventyNavigationBreadcrumb("Does not exist", { allowMissing: true }) %}
{{ navPages | dump | safe }}

This example has not yet been added—you can swap to another template language above! Or maybe you want to contribute it? Edit this page

Render the menu items using the `eleventyNavigationToHtml` or `eleventyNavigationToMarkdown` Filters

There are a couple of methods for rendering. Using the eleventyNavigationToHtml and eleventyNavigationToMarkdown filters will render the full navigation tree. Use this if you want to easily scale to an unlimited number of tiers/levels in your navigation. If you want full control of the markup, render the structure manually using the Copy and Paste templates example below. Use this if your navigation will have one level/tier of items.

With the Navigation structure returned from eleventyNavigation or eleventyNavigationBreadcrumb, we can render the navigation. Pass the object to the eleventyNavigationToHtml or eleventyNavigationToMarkdown filter to automatically output the full menu (as HTML or Markdown):

The eleventyNavigationToMarkdown filter is Added in Navigation 0.3.1.

Liquid Nunjucks 11ty.js 11ty.cjs

Syntax Liquid

{{ collections.all | eleventyNavigation | eleventyNavigationToHtml }}

{{ collections.all | eleventyNavigationBreadcrumb: "Bats" | eleventyNavigationToHtml }}

Syntax Nunjucks

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

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

This example has not yet been added—you can swap to another template language above! Or maybe you want to contribute it? Edit this page

Showing excerpts

You can also use this to display a longer list of navigation items with description text. This is useful for category/index pages. 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:

Liquid Nunjucks 11ty.js 11ty.cjs

Syntax Liquid

---
navToHtmlOptions:
  showExcerpt: true
---
{{ collections.all | eleventyNavigation: "Humans", navToHtmlOptions | json }}

Syntax Nunjucks

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

This example has not yet been added—you can swap to another template language above! Or maybe you want to contribute it? Edit this page

Advanced: All Rendering Options for `eleventyNavigationToMarkdown`

Added in Navigation 0.3.1

Liquid Nunjucks 11ty.js 11ty.cjs

Syntax Liquid

---
navToMdOptions:
  # Show excerpts (if they exist in data, read more above)
  showExcerpt: false
---
{{ collections.all | eleventyNavigation | eleventyNavigationToMarkdown: navToMdOptions | json }}

Syntax Nunjucks

---js
{
  navToMdOptions: {
    // Show excerpts (if they exist in data, read more above)
    showExcerpt: false
  }
}
---
{{ collections.all | eleventyNavigation | eleventyNavigationToMarkdown(navToMdOptions) | safe }}

This example has not yet been added—you can swap to another template language above! Or maybe you want to contribute it? Edit this page

Advanced: All 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!

Liquid Nunjucks 11ty.js 11ty.cjs

Syntax Liquid

---js
{
  navigationOptions: {
    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

    anchorClass: "",              // Add a class to the anchor
    activeAnchorClass: "",        // Add a class to the current page’s anchor

    // If matched, `activeListItemClass` and `activeAnchorClass` will be added
    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
  }
}
---
{{ collections.all | eleventyNavigation | eleventyNavigationToHtml: navigationOptions | json }}

Syntax Nunjucks

---js
{
  navigationOptions: {
    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

    anchorClass: "",              // Add a class to the anchor
    activeAnchorClass: "",        // Add a class to the current page’s anchor

    // If matched, `activeListItemClass` and `activeAnchorClass` will be added
    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
  }
}
---
{{ collections.all | eleventyNavigation | eleventyNavigationToHtml(navigationOptions) | safe }}

This example has not yet been added—you can swap to another template language above! Or maybe you want to contribute it? Edit this page

These work with eleventyNavigationBreadcrumb | eleventyNavigationToHtml too.

If you find yourself using a lot of these class options, maybe you should use the Advanced: Unlimited Child Levels example below and have full control of your HTML!

This template will render a single tier of items (no children) without using the eleventyNavigationToHtml or eleventyNavigationToMarkdown filters. This method gives you full control of the markup but is more complex with deeply nested menu structures.

Note that eleventyNavigationToMarkdown is Added in Navigation 0.3.1.

Liquid Nunjucks 11ty.js 11ty.cjs

Syntax Liquid

{% assign navPages = collections.all | eleventyNavigation %}
<ul>
{%- for entry in navPages %}
  <li{% if entry.url == page.url %} class="my-active-class"{% endif %}>
    <a href="{{ entry.url }}">{{ entry.title }}</a>
  </li>
{%- endfor %}
</ul>

Syntax Nunjucks

{% set navPages = collections.all | eleventyNavigation %}
<ul>
{%- for entry in navPages %}
  <li{% if entry.url == page.url %} class="my-active-class"{% endif %}>
    <a href="{{ entry.url }}">{{ entry.title }}</a>
  </li>
{%- endfor %}
</ul>

This example has not yet been added—you can swap to another template language above! Or maybe you want to contribute it? Edit this page

You can use a Nunjucks macro to recursively render list items of any depth but the code isn’t quite as clean:

Nunjucks Macro Code for Rendering Unlimited Child Levels:

Syntax Nunjucks

{% set navPages = collections.all | eleventyNavigation %}
{% macro renderNavListItem(entry) -%}
<li{% if entry.url == page.url %} class="my-active-class"{% endif %}>
  <a href="{{ entry.url }}">{{ entry.title }}</a>
{%- if entry.children.length -%}
  <ul>
    {%- for child in entry.children %}{{ renderNavListItem(child) }}{% endfor -%}
  </ul>
{%- endif -%}
</li>
{%- endmacro %}

<ul>
{%- for entry in navPages %}{{ renderNavListItem(entry) }}{%- endfor -%}
</ul>

Navigation Plugin

Template Compatibility

Installation

Adding Templates to the Navigation

Example

mammals.md

humans.md

bats.md

Use alternate text for the navigation link

Re-Ordering Items

Overriding the URL

Rendering the Navigation Menu (Easy Mode)

Output HTML

To Markdown

Advanced: Rendering the Navigation Bar (Deep Dive)

Fetch the menu items using the `eleventyNavigation` Filter

Example: Fetch all pages

Example: Get just one Branch

Render the menu items using the `eleventyNavigationToHtml` or `eleventyNavigationToMarkdown` Filters

Showing excerpts

Advanced: All Rendering Options for `eleventyNavigationToMarkdown`

Advanced: All Rendering Options for `eleventyNavigationToHtml`

Bring your own HTML: Render the menu items manually

Other pages in Official Plugins:

Navigation Plugin

Template Compatibility

Installation

Adding Templates to the Navigation

Example

mammals.md

humans.md

bats.md

Use alternate text for the navigation link

Re-Ordering Items

Overriding the URL

Rendering the Navigation Menu (Easy Mode)

Output HTML

To Markdown

Advanced: Rendering the Navigation Bar (Deep Dive)

Fetch the menu items using the eleventyNavigation Filter

Example: Fetch all pages

Example: Get just one Branch

Example: Breadcrumbs

Include the current page in breadcrumb results

Allow missing pages (nodes) in breadcrumbs

Render the menu items using the eleventyNavigationToHtml or eleventyNavigationToMarkdown Filters

Showing excerpts

Advanced: All Rendering Options for eleventyNavigationToMarkdown

Advanced: All Rendering Options for eleventyNavigationToHtml

Bring your own HTML: Render the menu items manually

Other pages in Official Plugins:

Fetch the menu items using the `eleventyNavigation` Filter

Render the menu items using the `eleventyNavigationToHtml` or `eleventyNavigationToMarkdown` Filters

Advanced: All Rendering Options for `eleventyNavigationToMarkdown`

Advanced: All Rendering Options for `eleventyNavigationToHtml`