Merge pull request #2439 from tschmidt/update-configuration-documentation

site/docs/configuration.md

@@ -278,40 +278,94 @@ before your site is served.
 
 ## Frontmatter defaults
 
-You can set default values for your [YAML frontmatter](../frontmatter/) variables
+Using [YAML front-matter](../frontmatter/) is one way that you can specify configuration in the pages and posts for your site. Setting things like a default layout, or customizing the title, or specifying a more precise date/time for the post can all be added to your page or post front-matter.
-in your configuration. This way, you can for example set default layouts or define
-defaults for your custom variables. Of course, any variable actually specified in
-the front matter overrides the defaults.
 
-All defaults go under the `defaults` key, which holds a list of scope-values combinations ("default sets").
+Often times, you will find that you are repeating a lot of configuration options. Setting the same layout in each file, adding the same category - or categories - to a post, etc. You can even add custom variables like author names, which might be the same for the majority of posts on your blog.
-The `scope` key defines for which files the defaults apply, limiting them by their source file `path` and
+
-optionally by their `type` (`page`, `post` or `draft`). The `values` key holds the actual list of defaults.
+Instead of repeating this configuration each time you create a new post or page, Jekyll provides a way to set these defaults in the site configuration. To do this, you can specify  site-wide defaults using the `defaults` key in the `_config.yml` file in your projects root directory.
+
+The `defaults` key holds an array of scope/values pairs that define what defaults should be set for a particular file path, and optionally, a file type in that path.
+
+Let's say that you want to add a default layout to all pages and posts in your site. You would add this to your `_config.yml` file:
 
-For example:
 {% highlight yaml %}
 defaults:
   -
     scope:
-      path: "" # empty string for all files
+      path: "" # an empty string here means all files in the project
+    values:
+      layout: "default"
+{% endhighlight %}
+
+Here, we are scoping the `values` to any file that exists in the scopes path. Since the path is set as an empty string, it will apply to **all files** in your project. You probably don't want to set a layout on every file in your project - like css files, for example - so you can also specify a `type` value under the `scope` key.
+
+{% highlight yaml %}
+defaults:
+  -
+    scope:
+      path: "" # an empty string here means all files in the project
+      type: "post"
+    values:
+      layout: "default"
+{% endhighlight %}
+
+Now, this will only set the layout for files where the type is `post`. The different types that are available to you are `page`, `post`, or `draft`. While `type` is optional, you must specify a value for `path` when creating a `scope/values` pair.
+
+As mentioned earlier, you can set multiple scope/values pairs for `defaults`.
+
+{% highlight yaml %}
+defaults:
+  -
+    scope:
+      path: ""
+      type: "post"
     values:
       layout: "my-site"
   -
     scope:
-      path: "about/blog"
+      path: "projects"
-      type: "post"
+      type: "page"
     values:
-      layout: "meta-blog" # overrides previous default layout
+      layout: "project" # overrides previous default layout
-      author: "Dr. Hyde"
+      author: "Mr. Hyde"
+      category: "project"
 {% endhighlight %}
 
-With these defaults, all pages and posts would default to the `my-site` layout except for the posts under `about/blog`,
+With these defaults, all posts would use the `my-site` layout. Any html files that exist in the `projects/` folder will use the `project` layout, if it exists. Those files will also have the `page.author` [liquid variable](../variables/) set to `Mr. Hyde` as well as have the category for the page set to `project`.
-who would default to the `meta-blog` layout and also have the `page.author` [liquid variable](../variables/) set to `Dr. Hyde` by default.
 
 ### Precedence
-You can have multiple sets of frontmatter defaults that specify defaults for the same setting. In this case, for each page or post,
+
-the default set with the more specific scope takes precedence. This way, you can specify defaults for a path like `/site/blog` that would
+Jekyll will apply all of the configuration settings you specify in the `defaults` section of your `_config.yml` file. However, you can choose to override settings from other scope/values pair by specifying a more specific path for the scope.
-override any defaults for `/site`. Also, if the paths are equal, a scope with a specified type is more specific. If two sets are equally
+
-specific, the bottom-most takes precedence.
+You can see that in the last example above. First, we set the default layout to `my-site`. Then, using a more specific path, we set the default layout for files in the `projects/` path to `project`. This can be done with any value that you would set in the page or post front-matter.
+
+Finally, if you set defaults in the site configuration by adding a `defaults` section to your `_config.yml` file, you can override those settings in a post or page file. All you need to do is specify the settings in the post or page front-matter. For example:
+
+{% highlight yaml %}
+# In _config.yml
+...
+defaults:
+  -
+    scope:
+      path: "projects"
+      type: "page"
+    values:
+      layout: "project"
+      author: "Mr. Hyde"
+      category: "project"
+...
+{% endhighlight %}
+
+{% highlight yaml %}
+# In projects/foo_project.md
+---
+author: "John Smith"
+layout: "foobar"
+---
+The post text goes here...
+{% endhighlight %}
+
+The `projects/foo_project.md` would have the `layout` set to `foobar` instead of `project` and the `author` set to `John Smith` instead of `Mr. Hyde` when the site is built.
 
 ## Default Configuration