dan
/
jekyll
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Changes to help clarify defaults in site config vs front-matter

This commit is contained in:
Terry Schmidt 2014-05-30 09:54:07 -05:00
parent 4dcb877ff9
commit 42cc3cac21
1 changed files with 16 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
site/docs/configuration.md
View File

@ -278,9 +278,9 @@ before your site is served.
## Frontmatter defaults ## Frontmatter defaults
Using [YAML front-matter](../frontmatter/) is one way that you can specify configuration in your pages and posts for your site. Things like setting 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. 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.
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 in your project. 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. 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.
@ -297,10 +297,7 @@ defaults:
layout: "default" layout: "default"
{% endhighlight %} {% endhighlight %}
Here, we are scoping the `values` to any file that exists in the scopes path. Since the path is 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.
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 %} {% highlight yaml %}
defaults: defaults:
@ -312,8 +309,7 @@ defaults:
layout: "default" layout: "default"
{% endhighlight %} {% endhighlight %}
Now, this will only set the layout for files where the type is `post`. The different types that 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.
are available to you are `page`, `post`, or `draft`.
As mentioned earlier, you can set multiple scope/values pairs for `defaults`. As mentioned earlier, you can set multiple scope/values pairs for `defaults`.
@ -335,23 +331,15 @@ defaults:
category: "project" category: "project"
{% endhighlight %} {% endhighlight %}
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. Those files will also have the `page.author` 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`.
[liquid variable](../variables/) set to `Mr. Hyde` as well as have the category for the page
set to `project`.
### Precedence ### Precedence
Jekyll will apply all of the configuration settings you specify in the `defaults` section of your 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.
`_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, 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.
using a more specific path, we set the default layout for posts in the `about/blog` path to
`meta-blog`. 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 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:
`_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 %} {% highlight yaml %}
# In _config.yml # In _config.yml
@ -359,34 +347,25 @@ is specify the settings in the post or page front-matter. For example:
defaults: defaults:
- -
scope: scope:
path: "" path: "projects"
type: "post" type: "page"
values: values:
layout: "my-site" layout: "project"
- author: "Mr. Hyde"
scope: category: "project"
path: "about/blog"
type: "post"
values:
layout: "meta-blog"
author: "Dr. Hyde"
category: "about"
... ...
{% endhighlight %} {% endhighlight %}
{% highlight yaml %} {% highlight yaml %}
# In about/blog/a_post.md # In projects/foo_project.md
--- ---
author: "John Smith" author: "John Smith"
layout: "foobar" layout: "foobar"
--- ---
The post text goes here...
Text for the post and such.
...
{% endhighlight %} {% endhighlight %}
The `about/blog/a_post.md` would have the layout set to `foobar` and the author set to `John Smith` 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.
when the site is built.
## Default Configuration ## Default Configuration