In the previous Eleventy tutorial, you saw the introduction of Eleventy, covering its basics, benefits, and notable features. In addition, you also learned how to create a simple static website using the 11ty Static Site Generator.
In this guide, you'll explore Eleventy Layouts and Templates, two fundamental features when working with an Eleventy site.
So, without further ado, let's get started!
Difference between Eleventy Layouts and Templates
In general, both terms — layout and template — are often used interchangeably. However, they serve different purposes and meanings in Eleventy's context.
Put simply, an Eleventy Layout file encompasses the markup or boilerplate code used to structure the main content, such as blog posts, static web pages, or product pages. Conversely, an Eleventy Template (or content) file contains the actual content, such as the body of a blog post.
Read on to learn more about how they differ and work.
Eleventy Templates
Eleventy Templates are essentially content files (e.g., blog posts or static pages) written in any template language like Markdown, HTML, JavaScript, Handlebars, or EJS. They hold the text or any other content that's rendered or output (usually inside a layout) when the site is built.
For example, a website's home page would usually be in an HTML template file, while blog articles would generally be in Markdown template files.
Typically, you'd have individual template files for each type of website content, such as different website pages or articles.
Working with Template Files
Creating and rendering (compiling) a template is straightforward.
Simply drop your template file in the input directory (more on this below) and build the site using the npx @11ty/eleventy command.
Then, Eleventy will compile and place the rendered template in the output directory (by default, _site).
As an example, suppose we have the following Markdown template file inside the input directory, named post.md:
# Heading
Example post content.
When the site is built, Eleventy will place the compiled Markdown file inside the output directory like so: _site/post/index.html
That was a breeze, right? But what if you want this template to have a nice layout? That's exactly what you'll learn in the Working with Layout Files section below.
Changing the Default Templates Input Directory
Given the flexibility of Eleventy, you can organize and structure your project as you like.
By default, Eleventy looks for and processes templates in the input directory, which is the current or root directory where Eleventy is installed.
You can specify a different templates directory should you decide to put all the templates separately. For this, you can use either the CLI argument or the Eleventy's configuration file, with the latter being the recommended approach.
So, for example, to instruct Eleventy to process all static pages (templates) in a directory called pages, you'd update the configuration file (.eleventy.js) as follows:
module.exports = function (eleventyConfig) {
return {
dir: {
input: 'pages'
},
};
};
Using Template Languages in Templates
You can use any template engine inside your template files. Some common choices include Liquid, Nunjucks, Haml, Pug, or Mustache.
Note that using the template engine's extension is not necessary for the template's file name. For example, a Liquid template can use a .html file extension.
Learn more about using different template languages on 11ty documentation.
Eleventy Layouts
Eleventy Layouts are special templates that wrap other templates or content files. Often, they contain repetitive or generic code that's reused throughout the website, such as the HTML's head section.
Typically, your template files would contain the textual data or other content paired with at least one layout file.
For instance, an HTML file that contains the basic markup (like the <head> and <footer> tags) for static pages would be considered a layout file.
Depending on your project's complexity and preferences, you can have as many layouts as needed or only a single layout file.
Working with Layout Files
Let's see how to use a layout in an Eleventy site. For this, we'll use the post.md file we created in the Working with Template Files section above.
First, create an _includes folder inside the input directory.
Then, create a base.html file within this new _includes folder.
Inside this HTML file, put the following HTML boilerplate code:
<!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 }}
</body>
</html>
Here, the {{ content }} data variable tag will populate the blog post content when the site is built. Similarly, the {{ title }} data variable tag will output the post title.
Now, open the post.md file and update it as follows:
---
layout: base.html
title: Web Dev Post
---
# Heading
Example post content.
Here, the layout key (inside the YAML front matter data) tells Eleventy to use the base.html layout to render this template. Furthermore, the title key sets the post title.
Finally, go ahead and build the site.
Once the site is built, open the compiled file and notice the new changes, such as the addition of the document title.
Changing the Default Layouts Directory
By default, Eleventy searches for the layouts inside the _includes directory. As with the templates above, you can use a separate folder to house all your layouts.
For instance, to use the layouts directory for layouts, you'd update the configuration file as follows:
module.exports = function (eleventyConfig) {
return {
dir: {
layouts: 'layouts'
},
};
};
Using Different Template Languages for Layouts
Eleventy gives you complete control to mix and use any template engine or language in your layout files. For example, a Markdown template can use a Liquid layout.
Using Subdirectories for Layout Files
If preferred, you can use subdirectories for layouts, allowing you to organize and structure your layouts neatly if you've lots of them.
For instance, you can update the above post example to use a subdirectory for the layout as follows:
---
layout: post/base.html
title: Web Dev Post
---
# Heading
Example post content.
Here, the layout key maps to the following: _includes/post/base.html
Layout Chaining
When a layout file utilizes another layout, it's considered as Layout Chaining. To understand this concept better, consider the following example.
Suppose you have a base layout that contains the essential HTML markup code that's used to populate your blog posts. We'll call it base.html (as created in the Working with Layout Files section above).
Say, if you decide to wrap your entire blog post content inside some HTML tag like <main> or <section>, then you'd need to create an additional (chained) layout file. We'll name it post-section.html.
Now, in your blog post's front matter data, instead of using base.html as the layout file, you'd use the new post-section.html, which itself would use the base.html layout file.
Here's how you'd update the above blog post example to accommodate this change.
First, update the post.md file like so:
---
layout: post-section.html
title: Web Dev Post
---
# Heading
Example post content.
Then, update the post-section.html file as follows:
---
layout: base.html
---
<section>
{{ content }}
</section>
When the site is built, it'll output the following HTML code:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Web Dev Post</title>
</head>
<body>
<section>
<h2>Heading</h2>
<p>Example post content.</p>
</section>
</body>
</html>
Conclusion
That sums up our guide on Eleventy Layouts and Templates. Be sure to check out the 11ty docs to explore all their features and possibilities.
As always, subscribe to the newsletter to stay updated on all the latest content and announcements. ✨
And before you leave, check out this short tutorial to learn how to easily create and maintain a sitemap for your Eleventy website. 🚀
