Eleventy's Data Cascade: Resolving Global, Directory, and Template Data Without Surprises

You add a layout key to a folder-level data file, rebuild, and suddenly every page in that folder ignores your global navigation settings. Eleventy did exactly what you told it to. The Data Cascade—the ordered merge of global data, directory data, and template front matter—is deterministic, but its strictness can feel like magic until you know the rules.

The useful takeaway: treat Eleventy's data resolution as a three-layer override system. Global _data files set the baseline, directory data files adjust that baseline for a folder and its children, and template front matter always wins. Knowing this order turns silent overrides into predictable configuration. The behavior described here is consistent across Eleventy 1.x and 2.x, but you should confirm details against the official documentation for your specific version.

The Three Layers, in Order

Eleventy builds a single data object for every template by merging sources in a fixed sequence. If two sources define the same key, the later source overwrites the earlier one.

1. Global data files

Any .json or .js file inside the _data directory becomes globally available to every template. This is the right place for site-wide constants: social handles, navigation menus, or a default layout.

// _data/site.json
{
  "title": "My Site",
  "defaultLayout": "base.njk",
  "showSearch": true
}

Because these files are read for every build, keep them lightweight. A .js file that fetches remote data or performs heavy computation will slow down every rebuild.

2. Directory data files

A directory data file—named after its folder, such as posts.json inside posts/—applies to every template in that directory and its subdirectories. It is the efficient way to configure a section of your site without repeating front matter.

// posts/posts.json
{
  "defaultLayout": "post.njk",
  "showSearch": false
}

Here, showSearch is disabled for the entire posts tree unless a child template explicitly re-enables it.

3. Template front matter

Front matter at the top of a template has the highest priority. It can override both directory and global data for that single page.

---
showSearch: true
---
Post content here.

In this example, the page renders with search enabled even though the directory data disabled it.

A Worked Example: Watching the Override Happen

Suppose you want to confirm that front matter beats directory data. Create the following files in your Eleventy project root.

1. Global data: _data/site.json

   {
     "layout": "base.njk",
     "theme": "light"
   }

2. Directory data: docs/docs.json

   {
     "theme": "dark"
   }

3. Template: docs/getting-started.md

   ---
   theme: light
   ---
   # Getting Started

Run the build from your project root:

npx @11ty/eleventy

Then inspect the generated HTML:

grep 'theme' _site/docs/getting-started/index.html

You should expect the output to reflect light, because the template front matter overrides the directory data file. If you remove the theme key from the front matter and rebuild, the same command should now show dark, proving the directory layer took over. If you delete docs/docs.json as well, the value should fall back to the global light.

Risk: If you edit docs/docs.json and introduce a typo in a key name, every template in docs/ silently inherits the mistake unless it carries its own front matter override.

Trade-offs and Limitations

The cascade is powerful, but it rewards restraint.

• Deep nesting is hard to debug. When global, directory, and front matter data interact across multiple folder levels, guessing the final value becomes error-prone. A practical check is to add a temporary template that dumps the merged object:

  <pre>{{ page | dump }}</pre>

  Render it to a file and open the result to see exactly which keys survived the cascade.

• Complex data files cost build time. A .js file in _data executes on every build. If it calls an API or parses large datasets, your incremental rebuilds will feel slow. Pre-compute heavy data outside Eleventy when possible.

• Priority is absolute. There is no deep merge behavior for conflicting scalar keys by default. A directory data file overwrites the global value wholesale. If you need to preserve global keys, repeat them in the directory file or front matter.

An Actionable Closing

Use the cascade as a default-and-exception system. Put stable, site-wide values in _data. Use directory data files for section-wide defaults like layouts or taxonomies. Reserve front matter for genuine per-page exceptions. When a value looks wrong, do not guess—add a temporary dump template, rebuild, and read the final object. Finally, verify the exact priority order against the official Eleventy documentation for your installed version, because the cascade is the one behavior that quietly shapes every other feature in your build.