Attempt to fix 11ty/eleventy#268

11ty · Jun 22, 2019 · 70d0271 · 70d0271
1 parent 969884b
commit 70d0271
Show file tree

Hide file tree

Showing 2 changed files with 22 additions and 16 deletions.
diff --git a/docs/config.md b/docs/config.md
@@ -129,7 +129,7 @@ module.exports = {
 
 ### Directory for Includes
 
-The includes directory is meant for layout templates, include files, extends files, partials, or macros. These files will not be processed as input files, but can be consumed by other templates.
+The includes directory is meant for [Eleventy layouts](/docs/layouts/), include files, extends files, partials, or macros. These files will not be processed as full template files, but can be consumed by other templates.
 
 | Includes Directory |  |
 | --- | --- |
@@ -153,10 +153,10 @@ module.exports = {
 
 ### Directory for Layouts (Optional) {% addedin "0.8.0" %}
 
-The layouts directory is optional and intended only for projects that don’t want their layout templates to live in the [Includes directory](#directory-for-includes). These files will not be processed as input files, but can be consumed by other templates.
+This configuration option is optional but useful if you want your [Eleventy layouts](/docs/layouts/) to live outside of the [Includes directory](#directory-for-includes). Just like the [Includes directory](#directory-for-includes), these files will not be processed as full template files, but can be consumed by other templates.
 
 <div class="elv-callout elv-callout-warn elv-callout-warn-block">
-  <p>This setting <strong>only applies</strong> to Eleventy's language-agnostic <a href="/docs/layouts/">layouts</a> (i.e. when defined in front matter or data files).</p>
+  <p>This setting <strong>only applies</strong> to Eleventy's language-agnostic <a href="/docs/layouts/">layouts</a> (when defined in front matter or data files).</p>
   <p>When using <code>{% raw %}{% extends %}{% endraw %}</code>, Eleventy will <strong>still search the <code>_includes</code> directory</strong>. See <a href="/docs/layouts/#addendum-about-existing-templating-features">this note about existing templating features</a>.</p>
 </div>
 

diff --git a/docs/layouts.md b/docs/layouts.md
@@ -6,34 +6,40 @@ tags:
 ---
 # 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:
-
-{% codetitle "layout-example.md" %}
+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 %}
 ```markdown
 ---
 layout: mylayout.njk
-title: My Rad Blog
+title: My Rad Markdown Blog Post
 ---
-# 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](/docs/config/#directory-for-layouts-(optional)) if you’d prefer that to having them live in your _includes folder._
 
-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.
+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.
 
-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.
+{% callout "info" %}If you omit the file extension (for example <code>layout: mylayout</code>), Eleventy will cycle through all of the supported template formats (<code>mylayout.*</code>) 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 %}
-``` html
+```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>
+    <title>{{ title }}</title>
   </head>
   <body>
     {{ content | safe }}
@@ -44,19 +50,19 @@ Next, we need to create a `mylayout.njk` file. It can contain any type of text,
 
 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).
+{% 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 <a href="/docs/data-template-dir/">how Eleventy merges data</a>.{% endcallout %}
 
 All of this will output the following HTML content:
 
-{% codetitle "_site/layout-example/index.html" %}
+{% 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 Blog</title>
+    <title>My Rad Markdown Blog Post</title>
   </head>
   <body>
     <h1>My Rad Markdown Blog Post</h1>
@@ -94,9 +100,9 @@ Configuration API: use `eleventyConfig.addLayoutAlias(from, to)` to add layout a
 
 ```js
 module.exports = function(eleventyConfig) {
+
   eleventyConfig.addLayoutAlias('post', 'layouts/post.njk');
 
-  return {};
 };
 ```