Mastering the Eleventy Data Cascade: Stop Repeating Your Front Matter

If you have a site with fifty blog posts, you probably don't want to manually type layout: 'post' and tags: ['posts'] into the front matter of every single Markdown file. Repeating this configuration is tedious and makes site-wide changes a nightmare.

The solution is the Eleventy Data Cascade. Instead of treating data as a flat file, Eleventy merges data from multiple sources based on a strict hierarchy. The key takeaway is that data defined closer to the individual template always overrides data defined at a global level.

How the Cascade Order Works

Eleventy resolves data in a specific sequence. If the same key exists in multiple places, the later source wins. The order of precedence (from lowest to highest) is:

• Global Data: Files in the _data folder (e.g., _data/site.json). These apply to every page on the site.
• Directory Data: Files named .11tydata.json. These apply to every template in that folder and its subfolders.
• Template Data: Files named .11tydata.json. These apply specifically to one template file.
• Front Matter: The YAML or JSON block at the top of your Markdown or HTML file. This is the most specific and usually the final word.
• Computed Data: JavaScript functions that run after the above sources are merged, allowing you to derive values based on other data.

Practical Implementation: Organizing a Blog

To implement this, structure your project to move common settings upward. Instead of per-file front matter, use a directory data file to handle the "heavy lifting" for a specific section.

The Configuration Example

Assume a project structure like this:

 project/
 ├── _data/site.json
 └── posts/
     ├── posts.11tydata.json
     ├── hello-world.md
     └── my-second-post.md

1. Global Site Data (_data/site.json)
Use this for branding and site-wide constants.

{
  "siteName": "Tech Insights",
  "baseUrl": "https://example.com"
}

2. Directory Data (posts/posts.11tydata.json)
This tells Eleventy that every file inside the /posts folder should use the post layout and be tagged as a post.

{
  "layout": "post-layout.njk",
  "tags": ["posts"]
}

3. Template Front Matter (posts/hello-world.md)
Now, your individual posts only need unique content.

---
title: "Hello World"
date: 2026-10-15
---
Welcome to my first post!

The Array Replacement Trap

One of the most common points of confusion in the cascade is how Eleventy handles different data types. Objects are deep-merged, but arrays are replaced.

If your posts.11tydata.json defines "tags": ["posts"] and you add tags: ["featured"] to the front matter of a specific post, the final result is ["featured"]—the original "posts" tag is gone. This happens because Eleventy assumes that if you provide a new array, you intend to overwrite the previous list entirely.

To avoid this, you can use a JavaScript data file (.11tydata.js) to programmatically merge arrays or use the eleventyImport key in your front matter to explicitly bring in data from other sources.

Verifying the Final Data Object

Because the cascade happens behind the scenes, it can be hard to tell exactly what data a page is receiving. To debug this, run the Eleventy build with the --dryrun flag. This allows you to inspect the computed data without writing files to the disk.

Run this command in your terminal from the project root:

npx @11ty/eleventy --dryrun --output=json

Risk: Be careful when using Computed Data (JS functions) to reference other data. If a function in site.11tydata.js tries to reference a value that is currently being computed for the same page, you may trigger a circular reference error, which will crash the build process.

Summary Checklist

• Global: _data/ for site-wide settings.
• Directory: folder.11tydata.json for section defaults.
• Template: Front matter for unique page content.
• Check: Use --dryrun to verify the merge result.