Eleventy 5.81s

Astro 12.52s

Layouts

Contents

Front Matter Data in Layouts
- Sources of Data
Layout Aliasing
Prevent double-escaping in layouts
Layout Chaining
Omitting the Layout’s File Extension

Eleventy Layouts are special templates that can be used to wrap other content.

To denote that a piece of content should be wrapped in a template, use the layout key in your front matter, like so:

View this example in: Markdown Liquid Nunjucks 11ty.js Handlebars

Filename index.md

Syntax Markdown

---
layout: mylayout.njk
title: My Rad Markdown Blog Post
---
# {{ title }}

Filename index.liquid

Syntax Liquid

---
layout: mylayout.njk
title: My Rad Liquid Blog Post
---
<h1>{{ title }}</h1>

Filename index.njk

Syntax Nunjucks

---
layout: mylayout.njk
title: My Rad Nunjucks Blog Post
---
<h1>{{ title }}</h1>

Filename index.11ty.js

Syntax JavaScript

module.exports = {
  data: {
    layout: "mylayout.njk",
    title: "My Rad JavaScript Blog Post"
  },
  render(data) {
    return `<h1>${data.title}</h1>`;
  }
}

Filename index.hbs

Syntax Handlebars

---
layout: mylayout.njk
title: My Rad Handlebars Blog Post
---
<h1>{{title}}</h1>

This will look for a mylayout.njk Nunjucks file in your includes folder at _includes/mylayout.njk.

You can use any template language in your layout file—it doesn’t need to match the template language of the content: an ejs template can use a njk layout.
Layouts can include subdirectories: layout: "layouts/base.njk" maps to _includes/layouts/base.njk.
You can have a separate folder for Eleventy layouts if you’d prefer to have them separate from your includes folder.

Next, we need to create a mylayout.njk file. It can contain any type of text, but here we’re using HTML:

Filename _includes/mylayout.njk

---
title: My Rad Blog
---

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ title }}</title>
  </head>
  <body>
    {{ content | safe }}
  </body>
</html>

Note that the layout template will populate the content data with the child template’s content. Also note that we don’t want to double-escape the output, so we’re using the provided Nunjucks safe filter here (see more language double-escaping syntax below).

Layouts can contain their own front matter data! It’ll be merged with the content’s data on render. Content data takes precedence, if conflicting keys arise. Read more about how Eleventy merges data in what we call the Data Cascade.

All of this will output the following HTML content to _site/content-using-layout/index.html:

View the output from: Markdown Liquid Nunjucks 11ty.js Handlebars

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Rad Markdown Blog Post</title>
  </head>
  <body>
    <h1>My Rad Markdown Blog Post</h1>
  </body>
</html>

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Rad Liquid Blog Post</title>
  </head>
  <body>
    <h1>My Rad Liquid Blog Post</h1>
  </body>
</html>

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Rad Nunjucks Blog Post</title>
  </head>
  <body>
    <h1>My Rad Nunjucks Blog Post</h1>
  </body>
</html>

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Rad JavaScript Blog Post</title>
  </head>
  <body>
    <h1>My Rad JavaScript Blog Post</h1>
  </body>
</html>

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Rad Handlebars Blog Post</title>
  </head>
  <body>
    <h1>My Rad Handlebars Blog Post</h1>
  </body>
</html>

Front Matter Data in Layouts Jump to heading

In Eleventy’s Data Cascade, front matter data in your template is merged with Layout front matter data! All data is merged ahead of time so that you can mix and match variables in your content and layout templates interchangeably.

Front matter data set in a content template takes priority over layout front matter! Chained layouts have similar merge behavior. The closer to the content, the higher priority the data.

INFO:

The placement in the data cascade for frontmatter data in layouts changed in 1.0! Take note of the new order below.

Sources of Data Jump to heading

When the data is merged in the Eleventy Data Cascade, the order of priority for sources of data is (from highest priority to lowest):

Layout Aliasing Jump to heading

Configuration API: use eleventyConfig.addLayoutAlias(from, to) to add layout aliases. Say you have a bunch of existing content using layout: post. If you don’t want to rewrite all of those values, map post to a new file like this:

Filename .eleventy.js

module.exports = function(eleventyConfig) {
  eleventyConfig.addLayoutAlias('post', 'layouts/post.njk');
};

Prevent double-escaping in layouts Jump to heading

Template Language	Unescaped Content (for layout content)	Comparison with an Escaped Output	Docs
Nunjucks	`{{ content \| safe }}`	`{{ value }}`	Docs
EJS	`<%- content %>`	`<%= value %>`	Docs
Handlebars	`{{{ content }}}` (triple stash)	`{{ value }}` (double stash)	Docs
Mustache	`{{{ content }}}` (triple stash)	`{{ value }}` (double stash)	Docs
Liquid	is by default unescaped so you can use `{{ content }}`	`{{ value \| escape }}`	Docs
HAML	`! #{ content }`	`= #{ content }`	Docs
Pug	`!{content}`	`#{value}`	Docs

Layout Chaining Jump to heading

Chaining multiple layouts together. Read more about Layout Chaining.

Omitting the Layout’s File Extension Jump to heading

Omitting the layout file extension (for example layout: mylayout) causes Eleventy to cycle through all of the supported template formats (mylayout.*) to look for a matching layout file. There are a few drawbacks to this approach:

It is slower! Including the file extension bypasses the file search.
It is ambiguous if you have multiple layout files with the same name and different extensions (e.g. mylayout.njk and mylayout.liquid).

You can disable extensionless layouts in your project with the setLayoutResolution Configuration API method Added in v2.0.0-beta.1 (we may swap this to be the default in a future major version of Eleventy):

Filename .eleventy.js

module.exports = function(eleventyConfig) {
  eleventyConfig.setLayoutResolution(false);
};

Layouts

Front Matter Data in Layouts Jump to heading #

Sources of Data Jump to heading #

Layout Aliasing Jump to heading #

Prevent double-escaping in layouts Jump to heading #

Layout Chaining Jump to heading #

Omitting the Layout’s File Extension Jump to heading #

Other pages in Working with Templates: