diff --git a/site/docs/configuration.md b/site/docs/configuration.md index bae427e1..e9a21db7 100644 --- a/site/docs/configuration.md +++ b/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 -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. +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. -All defaults go under the `defaults` key, which holds a list of scope-values combinations ("default sets"). -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. +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. + +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" - type: "post" + path: "projects" + type: "page" values: - layout: "meta-blog" # overrides previous default layout - author: "Dr. Hyde" + layout: "project" # overrides previous default layout + 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`, -who would default to the `meta-blog` layout and also have the `page.author` [liquid variable](../variables/) set to `Dr. Hyde` by default. +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`. ### 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 -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. + +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. + +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