Layouts Jump to heading
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:
---
layout: mylayout.njk
title: My Rad Markdown Blog Post
---
# {{ title }}
---
layout: mylayout.njk
title: My Rad Liquid Blog Post
---
<h1>{{ title }}</h1>
---
layout: mylayout.njk
title: My Rad Nunjucks Blog Post
---
<h1>{{ title }}</h1>
module.exports = {
data: {
layout: "mylayout.njk",
title: "My Rad JavaScript Blog Post"
},
render(data) {
return `<h1>${data.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 anjk
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.
- If you omit the file extension (for example
layout: mylayout
), Eleventy will cycle through all of the supported template formats (mylayout.*
) to look for a matching layout file. (This is slower, though)
Next, we need to create a mylayout.njk
file. It can contain any type of text, but here we’re using HTML:
---
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
:
<!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>
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.
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):
- Computed Data
- Front Matter Data in a Template
Front Matter Data in Layouts(only in 0.x) ⬅- Template Data Files
- Directory Data Files (and ascending Parent Directories)
- Front Matter Data in Layouts (moved in 1.0) ⬅
- Configuration API Global Data
- Global Data Files
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:
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.