eleventy-plugin-nav

Semi-automatic hierarchical navigation for 11ty.

Sidebar menus, breadcrumbs, next/previous page, all made easy with minimal work (often none) on your part.

This is intended to be used on websites whose URL structure largely mirrors their content structure, allowing you to get fully automated hierarchical navigation while only having to specify the exceptions — the common case is automatically inferred for you.

Installation

Just like any other plugin:

import eleventyNav from "eleventy-plugin-nav";

export default function (eleventyConfig) {
	// ...
	eleventyConfig.addPlugin(eleventyNav);
}

You can also provide options:

import eleventyNav from "eleventy-plugin-nav";

export default function (eleventyConfig) {
	// ...
	eleventyConfig.usePlugin(eleventyNav, {
		hidden: page => page.data.unlisted || page.data.customHiddenOption
	});
}

Configuration

Global Options

The following options are available to customize the plugin behavior:

| Option | Type | Default value | Description | | ------ | ---- | ------------- | ----------- | | sort | object | { "data.order": 1, "data.title": "" } | What to sort by and any default values. | | hidden | page: CollectionItem => boolean | page => page.data.unlisted | A function that takes a page and returns true if the page should be hidden from listings. | | areas | string[] | [] | A list of URLs for your site’s top-level "areas". If specified, the plugin will add area* data to each page, to facilitate top-level navigation menus, versioning, localization etc. |

Page-level Data

In general, you should not need to specify anything for common cases where URL structure and content hierarchy are aligned and the page order is the default. Stuff should just work. However, there are always anomalies, where you want to expose a different content hierarchy than what is inferred.

For example:

• Having external URLs as part of your sitemap
• Having pages whose children are not in child directories
• Having pages whose parent is not the URL-based ancestor
• etc.

Below, we list all data options you can specify on pages to override the default behavior. These are just 11ty data, so you can specify them in any way that is convenient: via the frontmatter, directory data etc.

parent

For pages whose parent is different than their URL-based ancestor, specify the parent property. The value is the parent slug, and can be either a sibling in the same directory, or an ancestor page. E.g. given two pages with URLs docs/items/foo and docs/items/foo-item, to make foo-item have the former as its parent you'd use parent: foo in its front matter.

Completely disconnected pages are not currently supported, but if you need this, please let us know!

order

By default, pages are sorted by title. To override, you can specify an order property. Its value is a number, and is 1 by default. Any (real) number is allowed — negative numbers, decimals, etc. Multiple pages can have the same order value, in which case they are sorted by title. For example, if you only use positive numbers < 100, you can make a page always appear before all others by using order: 0 and after all others by using order: 100.

unlisted

Do not include the page in any listings.

parentOf

Override the page’s children with a collection name. This is useful when you have a hierarchy where each page has a canonical parent, but also can be listed as a child of other pages.

For example, suppose you have a list of restaurants whose URL is restaurants/foo, and each restaurant has a list of dishes, whose URL is restaurants/foo/dishes/bar. However, you also want to have dishes/bar pages that list all restaurants that serve a given dish. Assuming each dish page was using a dish tag, you could specify parentOf: dish on the dish page across all restaurants.

Usage

The plugin adds several data items to every page, as well as some filters and collections that can be used to build navigation-related UI.

Page Data

This plugin makes several data items available on every page, which can be used to construct a variety of navigation-related UI, such as indices, navbars, breadcrumbs and the like.

| Data | Type | Description | | -------------- | ------------------ | ----------------------------------------------------------------------------- | | parent | string | Slug of parent page | | parentUrl | string | page.url of parent page | | parentItem | CollectionItem | Collection item for parent page | | children | CollectionItem[] | Array of a page's direct children | | lineage | CollectionItem[] | Array of a page's ancestors, starting from the root, plus the page itself. | | trail | CollectionItem[] | Array of a page's ancestors, excluding the root | | siblingIndex | number | The index of the current page among its parent’s children. -1 if no parent. | | siblings | CollectionItem[] | Other pages by the same parent. Excludes current page. | | hidden | boolean | Whether the page should be included in listings | | shown | boolean | Whether the page should be included in listings | | rootItem | CollectionItem | The item of the page’s homepage. | | areaUrl | string | The area URL of the site this page belongs to, if specified. "/" if no areas. | | areaItems | CollectionItem[] | A collection of the items for all top-level areas. | | areaItem | CollectionItem | The collection item for the area this page belongs to, if specified. Resolves to rootItem if no areas are specified. |

You can access this data by their names on the page itself, or on item.data on a collection item.

Filters

The plugin also adds several filters to help you work with the data. | Filter | Arguments | Description | | --------------- | --------- | --------------------------------------------------------------------------- | | isCurrentPage | url | Returns true if the page is the current page, based on the URL. | | isAncestorPage | url | Returns true if the page is an ancestor of the current page, based on the URL. | | isAncestorOrCurrentPage | url| Returnstrue` if the page is an ancestor or the current page, based on the URL. |

Collections

All collections added are sorted by the default sort order you specify.

| Collection | Description | | ---------- | ----------- | | roots | Contains all pages that are not children of any other page. Useful for creating a top-level navigation menu or listing all pages in the site. |

Examples / Recipes

Nested sidebar

• Sidebar
• Sidebar item

Breadcrumbs

• Basic breadcrumbs
• Advanced breadcrumbs (with menu of siblings)

You can find more recipes in _includes.