Leveraging Eleventy’s Data Cascade to Build Scalable Static Sites

Problem: Repetitive front matter across many pages

When you create a blog with dozens of posts, each page needs its own title, author, and other metadata. Writing the same front matter over and over becomes error‑prone and slows development.

Takeaway: Use Eleventy’s Data Cascade

The Data Cascade lets you define site‑wide defaults once and let higher‑specificity levels override them, so you write less code and keep data consistent.

Thesis: A concrete, verifiable approach

This post shows how the cascade works, provides a worked example you can run yourself, discusses a performance trade‑off, and gives a checklist to confirm the data flow is correct.

How the Data Cascade works

Eleventy evaluates data from four levels in this order:

• Global data – files in the _data folder (JSON or JS).
• Directory data – JSON files placed next to a folder of content (e.g., content/blog/site.json).
• Page front matter – YAML/JSON/YAML front matter at the top of a markdown file.
• Template data – data passed to a Nunjucks/Liquid template.

Higher‑specificity levels win; a page front matter value overrides directory data, which overrides global data.

Typical file layout

my-site/
├─ _data/
│   └─ site.json          # global data
├─ content/
│   ├─ blog/
│   │   └─ site.json      # directory‑level data for the blog folder
│   └─ posts/
│       └─ first-post.md  # page with front matter
└─ eleventy.config.js

Worked example

Follow these steps on a machine with Node ≥ 14 and Eleventy installed (npm i -D @11ty/eleventy). You need write permission for the project folder.

1. Create a global data file.
   # _data/site.json

   {
     "title": "My Site",
     "author": "Global Author"
   }

2. Add directory‑level data for the blog folder.
   # _data/blog/site.json

   {
     "author": "Blog Author"
   }

3. Write a markdown post with its own front matter.
   # content/posts/first-post.md

   ---
    title: "First Post"
    author: "John"
   ---
   This is the content of the first post.

4. Run the build and inspect the output.
   npx @11ty/eleventy

Resulting data hierarchy

The final HTML for first-post.html will contain:

<html>
  <head>
    <title>First Post</title>
    <meta name="author" content="John">
  </head>
  <body>
    <h1>First Post</h1>
    <p>This is the content of the first post.</p>
  </body>
</html>

Notice that author comes from the page front matter, overriding the directory value, which in turn overrides the global value.

Trade‑off: Build performance

Using JavaScript data files (.js) to fetch external APIs can dramatically increase build time as the site grows, because the build process must execute the async logic for every page. To mitigate this, keep dynamic fetching to a minimum or cache results.

Verification checklist

1. Create the three data files as shown above.
2. Run npx @11ty/eleventy and confirm the build finishes without errors.
3. Open the generated _site/posts/first-post.html and verify that the author meta tag reads "John" (page front matter) and that the page title is "First Post".
4. Check the console for any warnings about asynchronous data fetching if you later add a .js data file.

Closing: Actionable steps

1. Set up a _data folder and add a global JSON file for site‑wide variables.
2. For each logical section (e.g., blog), add a corresponding JSON file to inherit common metadata.
3. Use page front matter for values that differ per post.
4. Run the build, inspect the HTML, and confirm the cascade order with the checklist.
5. If you need dynamic data, move the logic to a separate build script and cache the result to keep build times reasonable.

By following this pattern you reduce duplication, maintain a single source of truth, and verify that the data behaves as expected before shipping your static site.