- Stable
3.0.0
Toggle Menu
1.93s
29.05s
Navigation Plugin
Contents
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
:
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);
};
Read more about Eleventy plugins.
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
.
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
.
Use alternate text for the navigation link
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.
Rendering the Navigation Menu (Easy Mode)
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
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.
Advanced: Rendering the Navigation Bar (Deep Dive)
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:
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
:
[
{
"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:
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"
}
]
Include the current page in breadcrumb results
Allow missing pages (nodes) in breadcrumbs
Added in Navigation 0.3.3
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.
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:
Advanced: All Rendering Options for eleventyNavigationToMarkdown
Added in Navigation 0.3.1
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!
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!
Bring your own HTML: Render the menu items manually
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.
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:
{% 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>