@ulu/eleventy-plugin-nav-tree

An Eleventy plugin to generate a hierarchical navigation tree from a collection. It provides filters for creating the tree structure, converting it to HTML, and filtering it to show only the active trail.

Installation

npm install @ulu/eleventy-plugin-nav-tree --save-dev

Usage

In your Eleventy configuration file (e.g., .eleventy.js), add the plugin:

const navTreePlugin = require("@ulu/eleventy-plugin-nav-tree");

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

Filters

This plugin provides three filters for use in your templates.

navTree

Creates a nested tree structure from an Eleventy collection.

Usage:

{% set nav = collections.all | navTree %}

Options: You can pass an options object to override the defaults from defaults.js.

{% set nav = collections.all | navTree({ section: true }) %}

navTreeToHtml

Renders a navigation tree object into an HTML <ul> list.

Usage:

{{ nav | navTreeToHtml | safe }}

Options: You can pass an options object to override the defaults from lib/defaults.js.

{{ nav | navTreeToHtml({ class: "my-menu", collapsible: true }) | safe }}

You can also change the default "Introduction" label by passing the collapsibleIndexLabel option.

{{ nav | navTreeToHtml({ collapsible: true, collapsibleIndexLabel: "Overview" }) | safe }}

A particularly useful option is formatLink, which allows you to customize the link text and markup.

formatLink

The formatLink option is a function that receives an object with the following properties:

• node: The current node in the navigation tree. The original Eleventy collection item is available at node.entry.
• options: The options object for the navTreeToHtml filter.
• isCollapsibleIndex: A boolean that is true only for the special "index" link created inside a collapsible section. This link represents the parent page of the section.

Default formatLink behavior:

function formatLink({ node, options, isCollapsibleIndex }) {
  const { data } = node.entry;
  
  return isCollapsibleIndex ?
    data.menuTitle || options.collapsibleIndexLabel :
    data.menuTitle || data.title;
}

As you can see, when isCollapsibleIndex is true, it defaults to "Introduction" if a menuTitle is not specified in the page's frontmatter. For all other links, it uses the menuTitle or the page's title.

Example of overriding formatLink:

{% set nav = collections.all | navTree %}
{{ nav | navTreeToHtml({
  formatLink: ({ node, isCollapsibleIndex }) => {
    if (isCollapsibleIndex) {
      return `<strong>${node.entry.data.title} (Overview)</strong>`;
    }
    return node.entry.data.title;
  }
}) | safe }}

navTreeActiveTrailOnly

Prunes a navigation tree to only include items that are in the direct path to the currently active page.

Usage:

{% set breadcrumbNav = collections.all | navTree | navTreeActiveTrailOnly %}
{{ breadcrumbNav | navTreeToHtml }}

Links

• Change Log