Layouts #

Layouts are 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:

Filename layout-example.md

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

This will look for a mylayout.njk Nunjucks template file in your _includes folder (_includes/mylayout.njk). You can use any template type in your layout—it doesn’t have to match the template type of the content. An ejs template can use a njk layout, for example.

If you omit the file extension (layout: mylayout), eleventy will cycle through all of the supported template formats (mylayout.*) to look for a matching layout file.

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

<!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 Nunjuck’s 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).

All of this will output the following HTML content:

Filename _site/layout-example/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 Blog</title>
  </head>
  <body>
    <h1>My Rad Markdown Blog Post
  </body>
</html>

Layouts in a Subdirectory #

New in v0.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 #

New in v0.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:

Filename .eleventy.js

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

  return {};
};

Prevent double-escaping in layouts #

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 #

Your layouts can also use a layout! Add the same layout front matter data to your layout template file and it’ll chain. You do not have to use the same template engine across layouts and content! You can mix and match.

To chain a layout, let’s look at an example:

Filename layout-chain-example.md

---
layout: mainlayout.njk
title: My Rad Blog
---
# My Rad Markdown Blog Post

We want to add a main element around our post’s content because we like accessibility. Here’s what mainlayout.njk would look like:

Filename _includes/mainlayout.njk

---
layout: mylayout.njk
---
<main>
  {{ content | safe }}
</main>

This layout would then be itself wrapped in the same mylayout.njk we used in our previous example:

Filename _includes/mylayout.njk

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

Used together, this would output:

Filename _site/layout-chain-example/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 Blog</title>
  </head>
  <body>
    <main>
      <h1>My Rad Markdown Blog Post
    </main>
  </body>
</html>

Addendum about existing Templating features #

It is worth noting that existing template reuse mechanisms built into different templating languages are still available to you. For instance, Nunjucks calls it Template Inheritance and exposes with {% extends %}. Eleventy’s layout system exists a layer above this and exposes a nice multi-template-language mechanism to configure layouts in your content’s front matter and share data between them.