1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
---
title: Front Matter
permalink: /docs/frontmatter/
---
The front matter is where Jekyll starts to get really cool. Any file that
contains a [YAML](http://yaml.org/) front matter block will be processed by
Jekyll as a special file. The front matter must be the first thing in the file
and must take the form of valid YAML set between triple-dashed lines. Here is a
basic example:
```yaml
---
layout: post
title: Blogging Like a Hacker
---
```
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.
<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
<a href="../windows/">Jekyll on Windows</a>.
</p>
</div>
<div class="note">
<h5>ProTip™: Front Matter Variables Are Optional</h5>
<p>
If you want to use <a href="../variables/">Liquid tags and variables</a>
but don’t need anything in your front matter, just leave it empty! The set
of triple-dashed lines with nothing in between will still get Jekyll to
process your file. (This is useful for things like CSS and RSS feeds!)
</p>
</div>
## Predefined Global Variables
There are a number of predefined global variables that you can set in the
front matter of a page or post.
<div class="mobile-side-scroller">
<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 the file extension. Layout files must be placed in the
<code>_layouts</code> directory.
</p>
<ul>
<li>
Using <code>null</code> will produce a file without using a layout
file. However this is overridden if the file is a post/document and has a
layout defined in the <a href="../configuration/#front-matter-defaults">
frontmatter defaults</a>.
</li>
<li>
Starting from version 3.5.0, using <code>none</code> in a post/document will
produce a file without using a layout file regardless of frontmatter defaults.
Using <code>none</code> in a page, however, will cause Jekyll to attempt to
use a layout named "none".
</li>
</ul>
</td>
</tr>
<tr>
<td>
<p><code>permalink</code></p>
</td>
<td>
<p>
If you need your processed blog post URLs to be something other than
the site-wide style (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 specific post to show up when the
site is generated.
</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note">
<h5>ProTip™: Render Posts Marked As Unpublished</h5>
<p>
To preview unpublished pages, simply run `jekyll serve` or `jekyll build`
with the `--unpublished` switch. Jekyll also has a handy <a href="../drafts/">drafts</a>
feature tailored specifically for blog posts.
</p>
</div>
## Custom Variables
Any variables in the front matter that are not predefined are mixed into 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:
```liquid
<!DOCTYPE HTML>
<html>
<head>
<title>{% raw %}{{ page.title }}{% endraw %}</title>
</head>
<body>
…
```
## Predefined Variables for Posts
These are available out-of-the-box to be used in the front matter for a post.
<div class="mobile-side-scroller">
<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. A date is specified in the
format <code>YYYY-MM-DD HH:MM:SS +/-TTTT</code>; hours, minutes, seconds, and timezone offset
are optional.
</p>
</td>
</tr>
<tr>
<td>
<p><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="https://en.wikipedia.org/wiki/YAML#Basic_components">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 <a
href="https://en.wikipedia.org/wiki/YAML#Basic_components">YAML list</a> or a
space-separated string.
</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note">
<h5>ProTip™: Don't repeat yourself</h5>
<p>
If you don't want to repeat your frequently used front matter variables
over and over, just define <a href="../configuration/#front-matter-defaults" title="Front Matter defaults">defaults</a>
for them and only override them where necessary (or not at all). This works
both for predefined and custom variables.
</p>
</div>
|
