Skip to content

Commit

Permalink
changes to frontmatter docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@cobyism
cobyism committed Sep 10, 2012
1 parent fa7d980 commit fceace6
Show file tree
Hide file tree
Showing 2 changed files with 89 additions and 21 deletions.
108 changes: 88 additions & 20 deletions _posts/2012-07-01-frontmatter.md
View file
Expand Up @@ -5,9 +5,7 @@ prev_section: configuration
next_section: posts
---

Any files that contain a [YAML](http://yaml.org/) front matter block
will be processed by Jekyll as special files. The front matter must be
the first thing in the file and takes the form of:
The front-matter is where Jekyll starts to get really cool. Any files that contain a [YAML](http://yaml.org/) front matter block will be processed by Jekyll as special files. The front matter must be the first thing in the file and must take the form of sets of variables and values set between triple-dashed lines. Here is a basic example:

{% highlight yaml %}
---
Expand All @@ -16,23 +14,69 @@ title: Blogging Like a Hacker
---
{% endhighlight %}

Between the triple-dashed lines, you can set predefined variables (see
below for a reference) or custom data of your own.
Between these triple-dashed lines, you can set predefined variables (see below for a reference) or even create custom ones of your own. These variables will then be available to you to access using Liquid tags both further down in the file and also in any layouts or includes that the page or post in question relies on.

\*IMPORTANT! (Especially for Windows users)\*

When you use `UTF-8` encoding for your file, make sure that
no `BOM` header chars exist in your file or everything will
blow up!
<div class="note warning">
<h5>UTF-8 Character Encoding Warning</h5>
<p>If you use UTF-8 encoding, make sure that no <code>BOM</code> header characters exist in your files or very, very bad things will happen to Jekyll. This is especially relevant if you’re running Jekyll on Windows.</p>
</div>

## Predefined Global Variables

Variable Description
`layout` If set, this specifies the layout file to use. Use the layout file name without file extension. Layout files must be placed in the `_layouts` directory.
`permalink` If you need your processed URLs to be something other than the default /year/month/day/title.html then you can set this variable and it will be used as the final URL.
`published` Set to false if you don’t want a post to show up when the site is generated.
`category`/@categories@ Instead of placing posts inside of folders, you can specify one or more categories that the post belongs to. When the site is generated the post will act as though it had been set with these categories normally.<br />Categories (plural key) can be specified as a [YAML list](http://en.wikipedia.org/wiki/YAML#Lists) or a space-separated string.
`tags` Similar to categories, one or multiple tags can be added to a post. Also like categories, tags can be specified as a YAML list or a space-separated string.
There are a number of predefined global variables that you can set in the front-matter of a page or post.

<table>
<thead>
<tr>
<th>Variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p><code>layout</code></p>
</td>
<td>
<p>If set, this specifies the layout file to use. Use the layout file name without file extension. Layout files must be placed in the <code>_layouts</code> directory.</p>
</td>
</tr>
<tr>
<td>
<p><code>permalink</code></p>
</td>
<td>
<p>If you need your processed URLs to be something other than the default <code>/year/month/day/title.html</code> then you can set this variable and it will be used as the final URL.</p>
</td>
</tr>
<tr>
<td>
<p><code>published</code></p>
</td>
<td>
<p>Set to false if you don’t want a post to show up when the site is generated.</p>
</td>
</tr>
<tr>
<td>
<p style="margin-bottom: 5px;"><code>category</code></p>
<p><code>categories</code></p>
</td>
<td>
<p>Instead of placing posts inside of folders, you can specify one or more categories that the post belongs to. When the site is generated the post will act as though it had been set with these categories normally. Categories (plural key) can be specified as a <a href="http://en.wikipedia.org/wiki/YAML#Lists">YAML list</a> or a space-separated string.</p>
</td>
</tr>
<tr>
<td>
<p><code>tags</code></p>
</td>
<td>
<p>Similar to categories, one or multiple tags can be added to a post. Also like categories, tags can be specified as a YAML list or a space-separated string.</p>
</td>
</tr>
</tbody>
</table>


## Custom Variables

Expand All @@ -41,12 +85,36 @@ the data that is sent to the Liquid templating engine during the
conversion. For instance, if you set a title, you can use that in your
layout to set the page title:

`<title>{{ "{{ page.title " }}}}</title>`
{% highlight html %}
<!DOCTYPE HTML>
<html>
<head>
<title>{{ "{{ page.title " }}}}</title>
</head>
<body>
...
{% endhighlight %}

## Predefined Variables for Post Front-Matter
## Predefined Variables for Posts

These are available out-of-the-box to be used in the front-matter for a
post.

Variable Description
`date` A date here overrides the date from the name of the post. This can be used to ensure correct sorting of posts.
<table>
<thead>
<tr>
<th>Variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p><code>date</code></p>
</td>
<td>
<p>A date here overrides the date from the name of the post. This can be used to ensure correct sorting of posts.</p>
</td>
</tr>
</tbody>
</table>
2 changes: 1 addition & 1 deletion css/style.css
View file
Expand Up @@ -522,7 +522,7 @@ td p {
th {
text-transform: uppercase;
font-size: 16px;
padding: .5em 0;
padding: .5em .75em;
text-shadow: 0 -1px 0 rgba(0,0,0,.9);
color: #888;
}
Expand Down

0 comments on commit fceace6

Please sign in to comment.