Choosing Eleventy’s Navigation Plugin vs. Manual Navigation: A Practical Decision Guide

Problem Statement

When building a static website with Eleventy, you often need a navigation menu that reflects the site’s hierarchy. You can either rely on Eleventy’s eleventyNavigation plugin, which auto‑generates a navigation tree from front‑matter, or write your own navigation logic in templates. The decision hinges on project constraints, maintenance effort, and desired control over markup.

Decision & Constraints

Decision: Use the Navigation Plugin if you want rapid setup, consistent ordering, and minimal code. Opt for a custom solution when you need bespoke markup, styling, or data sources that the plugin can’t accommodate.

Constraints to consider:

• Eleventy version compatibility (plugin must match Eleventy’s major/minor).
• Template language support (plugin works with Nunjucks, Liquid, EJS, but may not render correctly in Handlebars).
• Maintenance overhead (plugin updates vs. manual code changes).
• Desired markup structure (semantic HTML, ARIA roles, CSS frameworks).
• Future-proofing (plugin deprecations, custom logic stability).

Supported Options Comparison

Feature	Eleventy Navigation Plugin	Custom Navigation
Setup Effort	1‑2 lines in eleventy.config.js, add eleventyNavigation front‑matter.	Write helper functions or include files; maintain ordering logic.
Ordering & Hierarchy	Automatic tree from eleventyNavigation.order and eleventyNavigation.parent.	Manually compute parent/children or load from JSON/YAML.
Markup Control	Renders <nav><ul> by default; can customize via template.	Full control over tags, classes, ARIA attributes.
Template Language Support	Works with Nunjucks, Liquid, EJS (no Handlebars support documented).	Any language you can write logic in.
Dependency Management	Add @11ty/eleventy-navigation to package.json and lock version.	No extra dependencies.
Future Updates	Potential deprecation of eleventyNavigation key; monitor changelog.	Stable as long as you manage the code.

Trade‑Off Analysis

Speed vs. Control

The plugin slashes development time: you only add a front‑matter key and the tree appears. Custom navigation forces you to write and test logic, but you can shape the output to match design systems or accessibility guidelines.

Maintenance Burden

With the plugin, you rely on Eleventy's release cycle. A breaking change in a newer Eleventy version could require updating the plugin or changing the front‑matter key. Custom code is your responsibility; you can refactor without external dependencies.

Consistency Across Sites

If you run multiple sites with similar navigation, the plugin guarantees identical ordering logic. A custom solution might diverge if you forget to sync helper functions.

Template Language Compatibility

Eleventy’s plugin documentation lists Nunjucks, Liquid, and EJS. If your project uses Handlebars or a custom language, the plugin may not render the navigation, forcing you to implement it manually.

Concrete Implementation Example

1. Install the Plugin

npm install @11ty/eleventy-navigation --save-dev

Add to eleventy.config.js (run with Node 18+):

module.exports = function(eleventyConfig) {
  // Enable the Navigation Plugin
  eleventyConfig.addPlugin(require('@11ty/eleventy-navigation'));
  return {
    dir: {
      input: "src",
      output: "_site"
    }
  };
};

2. Markup Pages with Navigation Metadata

Create a simple page src/about.md:

---
title: About Us
eleventyNavigation:
  order: 2
  parent: Home
---

# About Us
Content goes here.

And src/index.md:

---
title: Home
eleventyNavigation:
  order: 1
---

# Welcome
Home page content.

3. Render Navigation in a Layout

In a Nunjucks layout (e.g., src/_includes/layouts/base.njk):

{% if navigation %}
  
    

      {% for item in navigation %}
        

          {{ item.title }}
          {% if item.children %}
            

              {% for child in item.children %}
                
{{ child.title }}
              {% endfor %}
            
          {% endif %}
        
      {% endfor %}
    
  
{% endif %}

The navigation variable is automatically injected by the plugin.

4. Verify the Plugin is Active

Run Eleventy in debug mode:

npx @11ty/eleventy --debug

Look for a line like:

✔  Building navigation… Done (0.12s)

If absent, the plugin isn’t loading; double‑check the require path and Node version.

5. Inspect Generated Navigation

Build the site (npx @11ty/eleventy) and open _site/index.html. Inspect the <nav> element to confirm the order: Home first, About second. Use the browser’s dev tools to verify the href values match the page URLs.

6. Optional: Customizing Markup

If you need a different structure (e.g., <nav><ol>), modify the layout. The plugin supplies the same navigation data; you control rendering.

Practical Checklist

• Is your Eleventy version ^0.13.0 (or newer) and compatible with @11ty/eleventy-navigation?
• Do you use a supported template language?
• Do you need a specific markup pattern that the plugin can’t produce?
• Can you tolerate a dependency that may evolve?
• Will you maintain the front‑matter order across many pages?

Answer “yes” to the first two and “no” to the last two → go with the plugin. Otherwise, implement navigation manually.

Limitations & Caveats

• The plugin relies on the eleventyNavigation front‑matter key; future releases might rename or deprecate it. Keep the plugin changelog under review.
• Large sites with thousands of pages may experience slower build times due to navigation tree construction.
• Custom navigation logic can be more performant if you can cache the tree or limit recursion.

Conclusion

The Eleventy Navigation Plugin offers a quick, consistent way to build hierarchical menus, especially for sites that fit its data model. If your project requires bespoke markup, advanced styling, or uses an unsupported template language, a hand‑crafted solution gives you the flexibility you need. Use the checklist above to decide, and follow the example to implement and verify your choice.