Eleventy: Global vs Directory Data Override Confusion

Short answer

Yes — by design, a directory-level site.json deterministically overrides _data/site.json for templates in that directory subtree. The data cascade merges sources in increasing priority: global data files (_data) are lowest, directory data files come next, and template front matter is highest. If you are seeing the global value win, something outside the simple cascade is almost always responsible.

Confirmed behavior vs. likely explanation

Confirmed: Eleventy does a deep merge by default. This is the most common source of confusion. If _data/site.json has {"nav": {"a": 1, "b": 2}} and your directory site.json has {"nav": {"b": 99}}, templates in that directory see a: 1, b: 99 — the directory value wins only for the keys it redefines; other nested keys are inherited from global. It can look like "the global file overrode mine" when really the merge combined both.

Likely explanations for apparent priority inversions:

• Computed data: eleventyComputed resolves after the cascade, so a computed value can override directory data and front matter. Check for computed keys matching your colliding key.
• Deep merge disabled: older configs may call setDataDeepMerge(false), which switches collisions to shallow replacement and changes what "wins" at nested levels.
• Custom data extensions: files added via addDataExtension join the same cascade and can collide with a .json file of the same basename.
• Scope misunderstanding: directory data applies only to its own subtree. Sibling directories with the same key never affect each other, and a deeper directory file overrides a shallower one within its subtree.

Verify it in two minutes

Create a minimal reproduction before assuming a bug:

# _data/site.json
{"key": "global"}

# posts/site.json
{"key": "dir"}

# posts/page.md (front matter + body)
{{ site.key }}

Build and the page should render dir. Then add a nested object with a non-colliding key to the global file and confirm that key still appears in the output — that confirms deep merge is active. Also check your version, because cascade and merge defaults have changed across major releases:

npx @11ty/eleventy --version

Review the data cascade docs for that major version rather than relying on generic advice.

Large global data files: build cost

Global data files are loaded once per build and cached in memory — Eleventy does not re-read them from disk for every template. The per-template cost is the cascade merge operating on already-loaded data. The practical impacts of a very large global file are:

• Memory: the parsed data is held for the duration of the build.
• Merge cost: deep-merging large objects into every template's data context adds CPU time proportional to data size and template count.
• Watch/serve mode: editing a global data file triggers a broad rebuild, since potentially every template depends on it. This is where big global files hurt most.

To measure rather than guess, run a build with Eleventy's debug output and compare timing with and without the large file:

DEBUG=Eleventy* npx @11ty/eleventy

Bottom line

The priority is deterministic: directory data beats global data, front matter beats both, computed data beats everything. When results look wrong, check for deep-merge inheritance, a computed key, or a version-specific config change before suspecting the cascade itself. If you can share your Eleventy version and whether the colliding key is a nested object, that would pin down which of these applies to your case.