Taming Content Redundancy with the Eleventy Data Cascade

The Front Matter Fatigue Problem

As a static site grows, you will inevitably hit a wall where you are copying and pasting the same metadata across dozens of files. Whether it is a category name, a specific layout, or a set of social media tags for a section of your site, repeating this in the front matter—the YAML or JSON block at the top of a content file—is a maintenance risk. If you decide to rename "Tutorials" to "Guides," you shouldn't have to run a find-and-replace across fifty Markdown files.

The solution is the Eleventy Data Cascade. Instead of treating data as a property of a single page, the cascade allows you to define data at different levels of specificity. The core takeaway is that Eleventy resolves data by moving from the most general source to the most specific, with the most specific value always winning.

Understanding the Hierarchy

The Data Cascade operates on a priority system. When Eleventy renders a page, it looks for data in this order (from lowest to highest priority):

• Global Data: Files in the _data directory. These are available to every single page on the site.
• Directory Data: JSON or JS files placed within a specific folder (e.g., category.json). Every file in that folder and its subfolders inherits this data.
• Template Data: The front matter located at the top of the individual .md or .njk file.

If a value for title is defined in all three places, the value in the template front matter is what appears in the final HTML.

Worked Example: Managing a Documentation Section

Imagine a site with a global site name, a specific "Docs" section with its own layout, and individual pages within that section.

1. Global Data

Create a file at _data/site.json. This handles site-wide configuration.

{
  "name": "TechDocs Hub",
  "base_url": "https://example.com"
}

2. Directory Data

Inside your /docs/ folder, create a file named docs.json. This ensures every page in the docs folder uses the same layout and shares a common category label without needing it in every file's front matter.

{
  "layout": "layout-docs.njk",
  "category": "Documentation",
  "showSidebar": true
}

3. Template Override

Now, create a specific page at /docs/installation.md. You can override the category if this specific page belongs elsewhere, or simply add page-specific data.

---
title: "Installing the CLI"
category: "Getting Started"
---
This page inherits layout-docs.njk and showSidebar: true from the directory data, but overrides the category.

Diagnostic Check: Verifying the Cascade

To verify which data is winning, you can temporarily output the data object in your template. In Nunjucks, use the dump filter:

<pre>{{ page.data | dump(2) }}</pre>

Run this on a page within your target directory. If showSidebar is true but category is "Getting Started", the cascade is functioning correctly. Run these commands from your project root with the necessary permissions to execute npm or npx:

npx @11ty/eleventy --serve

Risk: Be cautious with naming directory data files. If you name a file docs.json inside the /docs/ folder, Eleventy treats it as directory data. If you name it site.json inside _data/, it is global. Mixing these up can lead to data being applied to the entire site when you only intended it for one folder.

The Trade-off: Traceability

While the cascade eliminates redundancy, it introduces a "discovery" problem. When a page is rendering with a value you didn't expect, you can no longer look at the file itself to find the source. You have to mentally traverse the directory tree upward to _data to find where the value was defined.

To mitigate this, keep your directory data files named clearly after the folder they reside in, and avoid nesting directory data more than two or three levels deep.

Closing Action

Audit your current project for repeated front matter keys. If you see the same layout or category value in more than three files, move that data into a directory-level JSON file. This decouples your content from your configuration and makes site-wide structural changes a single-file edit.