eleventy-plugin-normalized-collections

eleventy-plugin-normalized-collections

Early Development Notice: This plugin is under active development. The API may change before reaching v1.0.0. Please report issues and feedback on GitHub.

Eleventy plugin for normalized collections with flattened frontmatter and automatic navigation. Creates collections that match component library expectations by bridging the gap between Eleventy's native collection format and component contracts.

Features

• Normalized Collections: Flattens frontmatter to top level (not nested under .data)
• Automatic Older/Newer Navigation: Computed data for collection item navigation
• Main Menu Generation: Creates mainMenu collection from pages with navigation.navLabel
• Breadcrumbs: Auto-generated breadcrumbs using navigation.breadcrumbs
• Pagination Params: Computed data for paginated collection pages
• Configurable Sorting: Sort by any nested property (e.g., card.date)
• Component Contract Compliance: Includes permalink property for URL references

Installation

npm install eleventy-plugin-normalized-collections

Usage

Add the plugin to your Eleventy configuration:

// eleventy.config.js
import normalizedCollections from 'eleventy-plugin-normalized-collections';

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(normalizedCollections, {
    collections: {
      blog: {
        glob: 'src/blog/*.md',
        sortBy: 'card.date',
        sortOrder: 'desc'
      },
      projects: {
        glob: 'src/projects/*.md',
        sortBy: 'title',
        sortOrder: 'asc'
      }
    }
  });
}

Options

Option	Type	Default	Description
collections	object	{}	Collection configuration object

Collection Configuration

Each collection accepts:

Option	Type	Default	Description
glob	string	Required	Glob pattern for source files
sortBy	string	None	Dot-notation path to sort property
sortOrder	string	'asc'	Sort order: 'asc' or 'desc'

Normalized Collection Items

Each item in a normalized collection includes:

{
  // All frontmatter properties flattened to top level
  title: 'My Blog Post',
  card: { date: '2025-01-15', summary: '...' },

  // Added by plugin
  permalink: 'blog/my-post',  // URL without leading/trailing slashes
  url: '/blog/my-post/',       // Original Eleventy URL
  inputPath: './src/blog/my-post.md',
  outputPath: './_site/blog/my-post/index.html',
  fileSlug: 'my-post'
}

Main Menu Collection

The plugin automatically creates a mainMenu collection from pages that have navigation.navLabel in their frontmatter:

# src/about.md
---
title: About Us
navigation:
  navLabel: About
  navIndex: 2
---

Access in templates:

{% for item in collections.mainMenu %}
  <a href="{{ item.path }}">{{ item.title }}</a>
{% endfor %}

Menu items are sorted by navigation.navIndex (defaults to 999 if not specified).

Older/Newer Navigation

The plugin adds computed data for navigating between collection items:

{# In a blog post template #}
{% if collection.blog.previous | length %}
  <a href="/{{ collection.blog.previous[0].permalink }}">
    Previous: {{ collection.blog.previous[0].title }}
  </a>
{% endif %}

{% if collection.blog.next | length %}
  <a href="/{{ collection.blog.next[0].permalink }}">
    Next: {{ collection.blog.next[0].title }}
  </a>
{% endif %}

For descending date order (newest first):

• previous = older post (published earlier)
• next = newer post (published later)

Breadcrumbs

Breadcrumbs are automatically generated for all pages:

<nav aria-label="Breadcrumb">
  <ol>
    {% for crumb in navigation.breadcrumbs %}
      <li>
        <a href="{{ crumb.path }}">{{ crumb.title }}</a>
      </li>
    {% endfor %}
  </ol>
</nav>

Breadcrumbs use titles from mainMenu when available, otherwise derive titles from URL segments.

Example output for /blog/my-post/:

[
  { title: 'Home', path: '/' },
  { title: 'Blog', path: '/blog/' },
  { title: 'My Post', path: '/blog/my-post/' }
];

Pagination Params

For pages using Eleventy's built-in pagination, the plugin computes pagingParams with template-friendly values. Add pagination to your content file frontmatter:

# src/blog.md
---
layout: sections.njk
permalink: /blog/{% if pagination.pageNumber > 0 %}{{ pagination.pageNumber }}/{% endif %}
pagination:
  data: collections.blog
  size: 10

sections:
  - container: section
    name: collection-list
    hasPagingParams: true
    collectionName: blog
---

The plugin computes these values automatically:

Property	Description
numberOfItems	Total items in the collection
numberOfPages	Total number of pagination pages
pageLength	Items per page (from pagination.size)
pageStart	Index of first item on current page
pageNumber	Current page number (1-indexed)

Access in templates:

{# Display pagination info #}
<p>Showing {{ pagingParams.pageLength }} of {{ pagingParams.numberOfItems }} posts</p>
<p>Page {{ pagingParams.pageNumber }} of {{ pagingParams.numberOfPages }}</p>

{# Build pagination links #}
{% if pagingParams.numberOfPages > 1 %}
  <nav aria-label="Pagination">
    {% for i in range(1, pagingParams.numberOfPages + 1) %}
      <a href="/blog/{% if i > 1 %}{{ i - 1 }}/{% endif %}">{{ i }}</a>
    {% endfor %}
  </nav>
{% endif %}

Note: pagingParams is only populated on pages that have Eleventy pagination configured. For non-paginated pages, it returns null.

Sorting

The plugin supports sorting by any nested property using dot notation:

{
  collections: {
    blog: {
      glob: 'src/blog/*.md',
      sortBy: 'card.date',      // Nested property
      sortOrder: 'desc'
    },
    alphabetical: {
      glob: 'src/pages/*.md',
      sortBy: 'title',          // Top-level property
      sortOrder: 'asc'
    }
  }
}

Sorting handles:

• Numbers: Numeric comparison
• Dates: Parsed as Date objects
• Strings: Locale-aware string comparison

Requirements

• Node.js >= 20.0.0
• Eleventy >= 2.0.0

License

MIT

Development Transparency

Portions of this project were developed with the assistance of AI tools including Claude and Claude Code. These tools were used to:

• Generate or refactor code
• Assist with documentation
• Troubleshoot bugs and explore alternative approaches

All AI-assisted code has been reviewed and tested to ensure it meets project standards.