Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
124 lines (94 sloc) 5.71 KB
eleventyNavigation
parent key order excerpt
Working with Templates
Layouts
1
Wrap content in other content.

Layouts

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, simply use the layout key in your front matter, like so:

{% codetitle "content-using-layout.md" %} {% raw %}

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

{% endraw %}

This will look for a mylayout.njk Nunjucks file in your includes folder (_includes/mylayout.njk). Note that you can have a separate folder for Eleventy layouts if you’d prefer that to having them live in your includes folder.

You can use any template language in your layout—it doesn’t need to match the template language of the content. An ejs template can use a njk layout, for example.

{% callout "info" %}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.{% endcallout %}

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

{% codetitle "_includes/mylayout.njk" %}

{% raw %}

---
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>

{% endraw %}

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 Nunjuck’s safe filter here (see more language double-escaping syntax below).

{% callout "info" %}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.{% endcallout %}

All of this will output the following HTML content:

{% codetitle "_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>

Front Matter Data in Layouts

Take note that 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.

Note that 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

{% include "datasources.md" %}

Layouts in a Subdirectory {% addedin "0.2.7" %}

Layouts can be a full path inside of the includes folder, like so:

---
layout: layouts/base.njk
---

This will look for _includes/layouts/base.njk.

Layout Aliasing {% addedin "0.2.8" %}

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, just map post to a new file like this:

{% codetitle ".eleventy.js" %}

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

Prevent double-escaping in layouts

{% raw %}

Template Language Unescaped Content (for layout content) Comparison with an Escaped Output Docs
Nunjucks `{{ content safe }}` {{ value }}
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}}`
HAML ! #{ content } = #{ content } Docs
Pug !{content} #{value} Docs
{% endraw %}

Layout Chaining

Chaining multiple layouts together. Read more about Layout Chaining.

You can’t perform that action at this time.