Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 320 lines (228 sloc) 11.306 kb
bffdeee @mojombo rename to Jekyll
mojombo authored
1 h1. Jekyll
d189e05 @mojombo first commit
mojombo authored
2
3a21a0b @mojombo break long lines in readme
mojombo authored
3 Jekyll is a simple, blog aware, static site generator. It takes a template
4 directory (representing the raw form of a website), runs it through Textile or
5 Markdown and Liquid converters, and spits out a complete, static website
6 suitable for serving with Apache or your favorite web server. Visit
7 "http://tom.preston-werner.com":http://tom.preston-werner.com to see an
8 example of a Jekyll generated blog.
9
10 To understand how this all works, open up my
11 "TPW":http://github.com/mojombo/tpw repo in a new browser window. I'll be
12 referencing the code there.
13
14 Take a look at
15 "index.html":http://github.com/mojombo/tpw/tree/master/index.html. This file
16 represents the homepage of the site. At the top of the file is a chunk of YAML
17 that contains metadata about the file. This data tells Jekyll what layout to
18 give the file, what the page's title should be, etc. In this case, I specify
19 that the "default" template should be used. You can find the layout files in
20 the "_layouts":http://github.com/mojombo/tpw/tree/master/_layouts directory.
21 If you open
22 "default.html":http://github.com/mojombo/tpw/tree/master/_layouts/default.html
23 you can see that the homepage is constructed by wrapping index.html with this
24 layout.
25
26 You'll also notice Liquid templating code in these files.
27 "Liquid":http://www.liquidmarkup.org/ is a simple, extensible templating
28 language that makes it easy to embed data in your templates. For my homepage I
29 wanted to have a list of all my blog posts. Jekyll hands me a Hash containing
30 various data about my site. A reverse chronological list of all my blog posts
31 can be found in <code>site.posts</code>. Each post, in turn, contains various
32 fields such as <code>title</code> and <code>date</code>.
33
34 Jekyll gets the list of blog posts by parsing the files in the
35 "_posts":http://github.com/mojombo/tpw/tree/master/_posts directory. Each
36 post's filename contains the publishing date and slug (what shows up in the
37 URL) that the final HTML file should have. Open up the file corresponding to a
38 blog post:
39 "2008-11-17-blogging-like-a-hacker.textile":http://github.com/mojombo/tpw/tree/master/_posts/2008-11-17-blogging-like-a-hacker.textile.
40 GitHub renders textile files by default, so to better understand the file,
41 click on the
42 "raw":http://github.com/mojombo/tpw/tree/master/_posts/2008-11-17-blogging-like-a-hacker.textile?raw=true
43 view to see the original file. Here I've specified the <code>post</code>
44 layout. If you look at that file you'll see an example of a nested layout.
45 Layouts can contain other layouts allowing you a great deal of flexibility in
46 how pages are assembled. In my case I use a nested layout in order to show
47 related posts for each blog entry. The YAML also specifies the post's title
48 which is then embedded in the post's body via Liquid.
49
50 Posts are handled in a special way by Jekyll. The date you specify in the
51 filename is used to construct the URL in the generated site. The example post,
52 for instance, ends up at
53 <code>http://tom.preston-werner.com/2008/11/17/blogging-like-a-hacker.html</code>.
54
55 Files that do not reside in directories prefixed with an underscore are
56 mirrored into a corresponding directory structure in the generated site. If a
57 file does not have a YAML preface, it is not run through the Liquid
58 interpreter. Binary files are copied over unmodified.
59
60 Jekyll is still a very young project. I've only developed the exact
61 functionality that I've needed. As time goes on I'd like to see the project
62 mature and support additional features. If you end up using Jekyll for your
63 own blog, drop me a line and let me know what you'd like to see in future
64 versions. Better yet, fork the project over at GitHub and hack in the features
65 yourself!
d189e05 @mojombo first commit
mojombo authored
66
574637a @mojombo flesh out readme a little bit
mojombo authored
67 h2. Example Proto-Site
d189e05 @mojombo first commit
mojombo authored
68
bffdeee @mojombo rename to Jekyll
mojombo authored
69 My own personal site/blog is generated with Jekyll.
d189e05 @mojombo first commit
mojombo authored
70
3a21a0b @mojombo break long lines in readme
mojombo authored
71 The proto-site repo
72 ("http://github.com/mojombo/tpw":http://github.com/mojombo/tpw) is converted
73 into the actual site
74 ("http://tom.preston-werner.com/":http://tom.preston-werner.com)
d189e05 @mojombo first commit
mojombo authored
75
b8ce181 @mojombo more info in the readme
mojombo authored
76 h2. Install
d189e05 @mojombo first commit
mojombo authored
77
b8ce181 @mojombo more info in the readme
mojombo authored
78 The best way to install Jekyll is via RubyGems:
79
528a18f @mojombo reorganize readme
mojombo authored
80 $ sudo gem install mojombo-jekyll -s http://gems.github.com/
b8ce181 @mojombo more info in the readme
mojombo authored
81
82 h2. Run
83
84 $ cd /path/to/proto/site
85 $ jekyll
86
3a21a0b @mojombo break long lines in readme
mojombo authored
87 This will generate the site and place it in /path/to/proto/site/_site. If
88 you'd like the generated site placed somewhere else:
528a18f @mojombo reorganize readme
mojombo authored
89
90 $ jekyll /path/to/place/generated/site
91
92 And if you don't want to be in the proto site root to run Jekyll:
93
94 $ jekyll /path/to/proto/site /path/to/place/generated/site
95
96 h2. Run Options
d6a0227 @mojombo update readme with --lsi info
mojombo authored
97
3a21a0b @mojombo break long lines in readme
mojombo authored
98 There is an autobuild feature that will regenerate your site if any of the
99 files change. The autobuild feature can be used on any of the invocations:
94bf6de @mojombo update readme
mojombo authored
100
101 $ jekyll --auto
102
d6a0227 @mojombo update readme with --lsi info
mojombo authored
103 By default, the "related posts" functionality will produce crappy results.
104 In order to get high quality results with a true LSI algorithm, you must
105 enable it (it may take some time to run if you have many posts):
106
107 $ jekyll --lsi
108
3a21a0b @mojombo break long lines in readme
mojombo authored
109 For static code highlighting, you can install Pygments (see below) and then
110 use that to make your code blocks look pretty. To activate Pygments support
111 during the conversion:
b8ce181 @mojombo more info in the readme
mojombo authored
112
528a18f @mojombo reorganize readme
mojombo authored
113 $ jekyll --pygments
b8ce181 @mojombo more info in the readme
mojombo authored
114
6b582ff @mojombo document liquid data
mojombo authored
115 h2. Data
116
3a21a0b @mojombo break long lines in readme
mojombo authored
117 Jekyll traverses your site looking for files to process. Any files with YAML
118 front matter (see below) are subject to processing. For each of these files,
119 Jekyll makes a variety of data available to the pages via the Liquid
120 templating system. The following is a reference of the available data.
0c270cb @mojombo better data docs
mojombo authored
121
122 h3. Global
123
124 site
125 Sitewide information.
126
127 page
128 For Posts, this is the union of the data in the YAML front matter and the
129 computed data (such as URL and date). For regular pages, this is just the
130 YAML front matter.
131
132 content
133 In layout files, this contains the content of the subview(s). In Posts or
134 pages, this is undefined.
135
6b582ff @mojombo document liquid data
mojombo authored
136 h3. Site
137
138 site.time
043fb15 @mojombo readme clarifications
mojombo authored
139 The current Time (when you run the jekyll command).
6b582ff @mojombo document liquid data
mojombo authored
140
141 site.posts
043fb15 @mojombo readme clarifications
mojombo authored
142 A reverse chronological list of all Posts.
6b582ff @mojombo document liquid data
mojombo authored
143
d48157c @mojombo move related_posts into site data
mojombo authored
144 site.related_posts
145 If the page being processed is a Post, this contains a list of up to ten
043fb15 @mojombo readme clarifications
mojombo authored
146 related Posts. By default, these are low quality but fast to compute. For
147 high quality but slow to compute results, run the jekyll command with the
148 --lsi (latent semantic indexing) option.
d48157c @mojombo move related_posts into site data
mojombo authored
149
6b582ff @mojombo document liquid data
mojombo authored
150 h3. Post
151
152 post.title
043fb15 @mojombo readme clarifications
mojombo authored
153 The title of the Post.
6b582ff @mojombo document liquid data
mojombo authored
154
155 post.url
043fb15 @mojombo readme clarifications
mojombo authored
156 The URL of the Post without the domain.
0d18c6b @mojombo readme data tweaks
mojombo authored
157 e.g. /2008/12/14/my-post.html
6b582ff @mojombo document liquid data
mojombo authored
158
159 post.date
043fb15 @mojombo readme clarifications
mojombo authored
160 The Date assigned to the Post.
6b582ff @mojombo document liquid data
mojombo authored
161
162 post.id
043fb15 @mojombo readme clarifications
mojombo authored
163 An identifier unique to the Post (useful in RSS feeds).
0d18c6b @mojombo readme data tweaks
mojombo authored
164 e.g. /2008/12/14/my-post
6b582ff @mojombo document liquid data
mojombo authored
165
166 post.content
043fb15 @mojombo readme clarifications
mojombo authored
167 The content of the Post.
6b582ff @mojombo document liquid data
mojombo authored
168
5c46fd6 @mojombo document yaml front matter
mojombo authored
169 h2. YAML Front Matter
170
3a21a0b @mojombo break long lines in readme
mojombo authored
171 Any files that contain a YAML front matter block will be processed by Jekyll
172 as special files. The front matter must be the first thing in the file and
173 takes the form of:
5c46fd6 @mojombo document yaml front matter
mojombo authored
174
8bea61e @mojombo fix formatting
mojombo authored
175 <pre>
5c46fd6 @mojombo document yaml front matter
mojombo authored
176 ---
177 layout: post
178 title: Blogging Like a Hacker
179 ---
8bea61e @mojombo fix formatting
mojombo authored
180 </pre>
5c46fd6 @mojombo document yaml front matter
mojombo authored
181
3a21a0b @mojombo break long lines in readme
mojombo authored
182 Between the triple-dashed lines, you can set predefined variables (see below
183 for a reference) or custom data of your own.
5c46fd6 @mojombo document yaml front matter
mojombo authored
184
185 h3. Predefined Global Variables
186
8fab783 @mojombo clarify front matter docs
mojombo authored
187 layout If set, this specifies the layout file to use. Use the layout file
188 name without file extension. Layout files must be placed in the
189 <code>_layouts</code> directory.
5c46fd6 @mojombo document yaml front matter
mojombo authored
190
191 h3. Predefined Post Variables
192
193 permalink
194 If you need your processed URLs to be something other than the default
195 /year/month/day/title.html then you can set this variable and it will
196 be used as the final URL.
197
198 h3. Custom Variables
199
200 Any variables in the front matter that are not predefined are mixed into the
201 data that is sent to the Liquid templating engine during the conversion. For
202 instance, if you set a <code>title</code>, you can use that in your layout to
203 set the page title:
204
8bea61e @mojombo fix formatting
mojombo authored
205 &lt;title&gt;{{ page.title }}&lt;/title&gt;
5c46fd6 @mojombo document yaml front matter
mojombo authored
206
1e9040f @mojombo add code highlighting docs to readme
mojombo authored
207 h2. Filters, Tags, and Blocks
208
3a21a0b @mojombo break long lines in readme
mojombo authored
209 In addition to the built-in Liquid filters, tags, and blocks, Jekyll provides
210 some additional items that you can use in your site.
1d7b30b @mojombo document filters
mojombo authored
211
212 h3. Date to XML Schema (Filter)
213
214 Convert a Time into XML Schema format.
215
216 {{ site.time | date_to_xmlschema }}
217
218 becomes
219
220 2008-11-17T13:07:54-08:00
221
222 h3. XML Escape (Filter)
223
224 Escape some text for use in XML.
225
226 {{ post.content | xml_escape }}
227
228 h3. Number of Words (Filter)
229
230 Count the number of words in some text.
231
232 {{ post.content | number_of_words }}
233
234 becomes
235
236 1337
237
238 h3. Include (Tag)
46169d3 @mojombo add include docs to readme
mojombo authored
239
240 If you have small page fragments that you wish to include in multiple places on your site, you can use the <code>include</code> tag.
241
242 <pre>{% include sig.textile %}</pre>
243
3a21a0b @mojombo break long lines in readme
mojombo authored
244 Jekyll expects all include files to be placed in an <code>_includes</code>
245 directory at the root of your source dir. So this will embed the contents of
246 <code>/path/to/proto/site/_includes/sig.textile</code> into the calling file.
46169d3 @mojombo add include docs to readme
mojombo authored
247
1d7b30b @mojombo document filters
mojombo authored
248 h3. Code Highlighting (Block)
1e9040f @mojombo add code highlighting docs to readme
mojombo authored
249
250 Jekyll has built in support for syntax highlighting of over "100
251 languages":http://pygments.org/languages/ via "Pygments":http://pygments.org/.
f57bb07 @mojombo remind about --pygments in readme
mojombo authored
252 In order to take advantage of this you'll need to have Pygments installed, and
3a21a0b @mojombo break long lines in readme
mojombo authored
253 the pygmentize binary must be in your path. When you run Jekyll, make sure you
254 run it with Pygments support:
f57bb07 @mojombo remind about --pygments in readme
mojombo authored
255
256 $ jekyll --pygments
1e9040f @mojombo add code highlighting docs to readme
mojombo authored
257
258 To denote a code block that should be highlighted:
259
260 <pre>
261 {% highlight ruby %}
262 def foo
263 puts 'foo'
264 end
265 {% endhighlight %}
266 </pre>
267
268 The argument to <code>highlight</code> is the language identifier. To find the
269 appropriate identifier to use for your favorite language, look for the "short
270 name" on the "Lexers":http://pygments.org/docs/lexers/ page.
271
272 In order for the highlighting to show up, you'll need to include a
273 highlighting stylesheet. For an example stylesheet you can look at
274 "syntax.css":http://github.com/mojombo/tpw/tree/master/css/syntax.css. These
275 are the same styles as used by GitHub and you are free to use them for your
276 own site.
277
b8ce181 @mojombo more info in the readme
mojombo authored
278 h2. Contribute
279
280 If you'd like to hack on Jekyll, grab the source from GitHub. To get
281 all of the dependencies, install the gem first.
d189e05 @mojombo first commit
mojombo authored
282
bffdeee @mojombo rename to Jekyll
mojombo authored
283 $ git clone git://github.com/mojombo/jekyll
b8ce181 @mojombo more info in the readme
mojombo authored
284
285 The best way to get your changes merged back into core is as follows:
286
31aa865 @mojombo proper list syntax
mojombo authored
287 # Fork mojombo/jekyll on GitHub
288 # Clone down your fork
289 # Create a topic branch to contain your change
290 # Hack away
94bf6de @mojombo update readme
mojombo authored
291 # Do not change the version number, I will do that on my end
31aa865 @mojombo proper list syntax
mojombo authored
292 # If necessary, rebase your commits into logical chunks, without errors
293 # Push the branch up to GitHub
94bf6de @mojombo update readme
mojombo authored
294 # Send me (mojombo) a pull request for your branch
d189e05 @mojombo first commit
mojombo authored
295
574637a @mojombo flesh out readme a little bit
mojombo authored
296 h2. License
d189e05 @mojombo first commit
mojombo authored
297
298 (The MIT License)
299
574637a @mojombo flesh out readme a little bit
mojombo authored
300 Copyright (c) 2008 Tom Preston-Werner
d189e05 @mojombo first commit
mojombo authored
301
302 Permission is hereby granted, free of charge, to any person obtaining
303 a copy of this software and associated documentation files (the
304 'Software'), to deal in the Software without restriction, including
305 without limitation the rights to use, copy, modify, merge, publish,
306 distribute, sublicense, and/or sell copies of the Software, and to
307 permit persons to whom the Software is furnished to do so, subject to
308 the following conditions:
309
310 The above copyright notice and this permission notice shall be
311 included in all copies or substantial portions of the Software.
312
313 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
314 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
315 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
316 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
317 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
318 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
319 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.