Movatterモバイル変換

[0]ホーム
URL:

Skip to navigationSkip to main content
Blog
Eleventy, 2024 in Review
Versions
Stable
3.0.0
Canary
3.0.1-alpha.5
Menu
Eleventy1.93s
Gatsby29.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 foreleventy-navigationv0.3.x.
  • GitHub.

Template Compatibility

  • Any template language can add to navigation.
  • Any template language compatible withUniversal Filters can render the navigation menu.

Installation

Available onnpm.

npm install @11ty/eleventy-navigation

Open up your Eleventy config file (probablyeleventy.config.js) and useaddPlugin:

eleventy.config.js
import eleventyNavigationPluginfrom"@11ty/eleventy-navigation";

exportdefaultfunction(eleventyConfig){
eleventyConfig.addPlugin(eleventyNavigationPlugin);
};
const eleventyNavigationPlugin=require("@11ty/eleventy-navigation");

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

Read more aboutEleventy plugins.

Adding Templates to the Navigation

Add theeleventyNavigation object to your front matter data (or in adata directory file). Assign a unique string to thekey property inside ofeleventyNavigation.

Example

mammals.md

---
eleventyNavigation:
key: Mammals
---

This gives us:

  • Mammals

humans.md

To nest a template inside of the Mammals template, useparent: Mammals:

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

Any templates that do not haveparent 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? Useparent: Humans orparent: Bats. If you want to add another root template, leave outparent.

Use alternate text for the navigation link

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

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

Re-Ordering Items

To ensure that Humans comes first before Bats, use theorder 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 aurl key.

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

Usepermalink: 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 supportuniversal filters are supported. If you’re tired of reading, just use one of the following. These are usingthe filters documented below. If you want more control or need additional customization, keep reading!

Output HTML

SyntaxLiquid
{{ collections.all|eleventyNavigation|eleventyNavigationToHtml}}
SyntaxNunjucks
{{collections.all|eleventyNavigation|eleventyNavigationToHtml|safe}}
SyntaxWebC
<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

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.

SyntaxLiquid
{{ collections.all|eleventyNavigation|eleventyNavigationToMarkdown}}
SyntaxNunjucks
{{collections.all|eleventyNavigation|eleventyNavigationToMarkdown|safe}}
SyntaxWebC
<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

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: Rendering the Navigation Bar (Deep Dive)

Fetch the menu items using theeleventyNavigation Filter

TheeleventyNavigation filter returns asorted array of objects withurl andtitle properties (sorted usingorder, as noted above). If an entry has nested children, it will also include achildren property with an array of similar objects (and those may containchildren too, and so on).

Example: Fetch all pages

For our documented templates above with the following template:

SyntaxLiquid
{%assign navPages= collections.all|eleventyNavigation%}
{{ navPages|json}}
SyntaxNunjucks
{%setnavPages=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

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 intoeleventyNavigation. It doesn’t have to becollections.all!

Shows thatnavPages 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 toeleventyNavigation:

SyntaxLiquid
{%assign navPages= collections.all|eleventyNavigation:"Mammals"%}
{{ navPages|json}}
SyntaxNunjucks
{%setnavPages=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

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 toeleventyNavigationBreadcrumb like this:

SyntaxLiquid
{%assign navPages= collections.all|eleventyNavigationBreadcrumb:"Bats"%}
{{ navPages|json}}
SyntaxNunjucks
{%setnavPages=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

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"
}
]
Include the current page in breadcrumb results
SyntaxLiquid
---
navOptions:
  includeSelf: true
---
{%assign navPages= collections.all|eleventyNavigationBreadcrumb:"Mammals", navOptions%}
{{ navPages|json}}
SyntaxNunjucks
{%setnavPages=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

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

SyntaxLiquid
---
navOptions:
  allowMissing: true
---
{%assign navPages= collections.all|eleventyNavigationBreadcrumb:"Does not exist", navOptions%}
{{ navPages|json}}
SyntaxNunjucks
{%setnavPages=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

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 theeleventyNavigationToHtml oreleventyNavigationToMarkdown Filters

There are a couple of methods for rendering. Using theeleventyNavigationToHtml andeleventyNavigationToMarkdown 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 fromeleventyNavigation oreleventyNavigationBreadcrumb, we can render the navigation. Pass the object to theeleventyNavigationToHtml oreleventyNavigationToMarkdown filter to automatically output the full menu (as HTML or Markdown):

TheeleventyNavigationToMarkdown filter isAdded in Navigation 0.3.1.

SyntaxLiquid
{{ collections.all|eleventyNavigation|eleventyNavigationToHtml}}
{{ collections.all|eleventyNavigationBreadcrumb:"Bats"|eleventyNavigationToHtml}}
SyntaxNunjucks
{{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

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. Addexcerpt to theeleventyNavigation object.

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

When you render a navigation list, passshowExcerpt: true to theeleventyNavigationToHtml filter, like so:

SyntaxLiquid
---
navToHtmlOptions:
  showExcerpt: true
---
{{ collections.all|eleventyNavigation:"Humans", navToHtmlOptions|json}}
SyntaxNunjucks
---
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

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 foreleventyNavigationToMarkdown

Added in Navigation 0.3.1

SyntaxLiquid
---
navToMdOptions:
  # Show excerpts (if they exist in data, read more above)
  showExcerpt: false
---
{{ collections.all|eleventyNavigation|eleventyNavigationToMarkdown: navToMdOptions|json}}
SyntaxNunjucks
---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

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 foreleventyNavigationToHtml

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!

SyntaxLiquid
---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}}
SyntaxNunjucks
---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

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 witheleventyNavigationBreadcrumb | eleventyNavigationToHtml too.

If you find yourself using a lot of theseclass options, maybe you should use theAdvanced: 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 theeleventyNavigationToHtml oreleventyNavigationToMarkdown filters. This method gives you full control of the markup but is more complex with deeply nested menu structures.

Note thateleventyNavigationToMarkdown isAdded in Navigation 0.3.1.

SyntaxLiquid
{%assign navPages= collections.all|eleventyNavigation%}
<ul>
{%-for entryin navPages%}
<li{%if entry.url==page.url%}class="my-active-class"{%endif%}>
<ahref="{{ entry.url}}">{{ entry.title}}</a>
</li>
{%-endfor%}
</ul>
SyntaxNunjucks
{%setnavPages=collections.all|eleventyNavigation%}
<ul>
{%-forentryinnavPages%}
<li{%ifentry.url==page.url%}class="my-active-class"{%endif%}>
<ahref="{{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

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

Youcan 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:
SyntaxNunjucks
{% set navPages = collections.all | eleventyNavigation %}
{% macro renderNavListItem(entry) -%}
<li{% if entry.url == page.url %}{% endif %}>
<ahref="{{ 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>

Other pages in Official Plugins:

[8]ページ先頭
©2009-2025 Movatter.jp