Diagnosing Missing Layouts and Template Inheritance in Eleventy

The Problem: Raw Content Rendering

When Eleventy (11ty) fails to apply a layout, the generated HTML file contains only the raw content of the template—missing the <head>, <body>, and navigation elements. This usually manifests as a page that looks like plain text or unstyled HTML in the browser, despite the layout file existing in your project directory.

Rapid Diagnostic Table

Symptom	Likely Cause	Primary Check
Page is plain text/raw content	Missing or misspelled layout key	Front matter of the content file
Layout works locally, fails on CI/CD	Case-sensitivity mismatch	Filename casing vs. front matter string
Layout is ignored for entire folder	Directory Data File override	folder.json or folder.11tydata.js
Build hangs or crashes	Circular inheritance loop	Layout A referencing Layout A

Step-by-Step Resolution Path

Follow these checks in order to isolate where the inheritance chain is breaking. These steps assume you are using Eleventy v2.0 or later.

1. Validate the Layout Directory Configuration

Eleventy needs to know where your layout files live. If you have changed the default directory, ensure your .eleventy.js (or eleventy.config.js) reflects this.

module.exports = function(eleventyConfig) {
  return {
    // Ensure this path matches your actual folder structure
    dir: {
      input: "src",
      layouts: "src/_includes/layouts"
    }
  };
};

Risk: If layouts is defined as a subfolder of input, Eleventy looks relative to that path. Ensure you aren't accidentally nesting the path twice (e.g., src/_includes/layouts inside a src input directory).

2. Verify Front Matter Accuracy

Check the top of your content file (Markdown, Nunjucks, or Liquid). The layout key must point to the file name relative to the layouts directory.

Example Configuration: If your file is at src/_includes/layouts/base.njk, your content file should look like this:

---
layout: base.njk
title: My Page
---
Content goes here.

• Check: Does the filename in the front matter match the disk exactly?
• Check: Did you include the extension? While some configurations allow omitting it, including .njk or .liquid prevents ambiguity.

3. Inspect for Case-Sensitivity Issues

Local development on macOS or Windows is often case-insensitive, but Linux-based deployment servers (like Netlify or Vercel) are strict. If your file is named Base.njk but your front matter says layout: base.njk, the build will fail in production.

4. Audit Directory Data Files

If a specific folder's pages are all missing layouts, check for a .json or .11tydata.js file in that directory. These files apply settings to all files in the folder and will override individual front matter if not handled correctly.

Example posts.json:

{
  "layout": "layouts/post-layout.njk"
}

If this file contains a typo in the path, every post in that folder will render as raw content regardless of the individual file's front matter.

Handling Inheritance Loops

Eleventy allows layouts to wrap other layouts. However, if main.njk specifies layout: main.njk, the engine enters an infinite loop. If your build process hangs without an error message, check your layout files for self-referencing front matter.

Verification and Testing

To verify the fix, run your local server:

npx @11ty/eleventy --serve

1. Open the browser and view the page source (Ctrl+U / Cmd+Option+U).
2. Search for a unique tag from your layout file (e.g., <footer>).
3. If the tag is missing, check the terminal output. Eleventy typically prints a warning: Template not found: [path] during the build phase.

Rollback Procedure

If you modified .eleventy.js to change the layouts directory and the site broke further:

1. Revert the dir.layouts value to the previous path.
2. Delete the _site output folder to clear cached fragments.
3. Restart the build process.