Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 406 lines (293 sloc) 14.546 kb
bffdeee Tom Preston-Werner rename to Jekyll
mojombo authored
1 h1. Jekyll
d189e05 Tom Preston-Werner first commit
mojombo authored
2
3a21a0b Tom Preston-Werner 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
3a8f7a8 Added post categories based on directories containing _posts
Mark Reid authored
34 Jekyll gets the list of blog posts by parsing the files in any
35 "_posts":http://github.com/mojombo/tpw/tree/master/_posts directory found in
36 subdirectories below the root.
37 Each post's filename contains the publishing date and slug (what shows up in the
3a21a0b Tom Preston-Werner break long lines in readme
mojombo authored
38 URL) that the final HTML file should have. Open up the file corresponding to a
39 blog post:
40 "2008-11-17-blogging-like-a-hacker.textile":http://github.com/mojombo/tpw/tree/master/_posts/2008-11-17-blogging-like-a-hacker.textile.
41 GitHub renders textile files by default, so to better understand the file,
42 click on the
43 "raw":http://github.com/mojombo/tpw/tree/master/_posts/2008-11-17-blogging-like-a-hacker.textile?raw=true
44 view to see the original file. Here I've specified the <code>post</code>
45 layout. If you look at that file you'll see an example of a nested layout.
46 Layouts can contain other layouts allowing you a great deal of flexibility in
47 how pages are assembled. In my case I use a nested layout in order to show
48 related posts for each blog entry. The YAML also specifies the post's title
49 which is then embedded in the post's body via Liquid.
50
51 Posts are handled in a special way by Jekyll. The date you specify in the
52 filename is used to construct the URL in the generated site. The example post,
53 for instance, ends up at
54 <code>http://tom.preston-werner.com/2008/11/17/blogging-like-a-hacker.html</code>.
55
dad9a31 Tom Preston-Werner fix categories and add topics
mojombo authored
56 Categories for posts are derived from the directory structure the posts were
57 found within. A post that appears in the directory foo/bar/_posts is placed in
58 the categories 'foo' and 'bar'. By selecting posts from particular categories
59 in your Liquid templates, you will be able to host multiple blogs within a
60 site.
3a8f7a8 Added post categories based on directories containing _posts
Mark Reid authored
61
3a21a0b Tom Preston-Werner break long lines in readme
mojombo authored
62 Files that do not reside in directories prefixed with an underscore are
63 mirrored into a corresponding directory structure in the generated site. If a
64 file does not have a YAML preface, it is not run through the Liquid
65 interpreter. Binary files are copied over unmodified.
66
67 Jekyll is still a very young project. I've only developed the exact
68 functionality that I've needed. As time goes on I'd like to see the project
69 mature and support additional features. If you end up using Jekyll for your
70 own blog, drop me a line and let me know what you'd like to see in future
71 versions. Better yet, fork the project over at GitHub and hack in the features
72 yourself!
d189e05 Tom Preston-Werner first commit
mojombo authored
73
574637a Tom Preston-Werner flesh out readme a little bit
mojombo authored
74 h2. Example Proto-Site
d189e05 Tom Preston-Werner first commit
mojombo authored
75
bffdeee Tom Preston-Werner rename to Jekyll
mojombo authored
76 My own personal site/blog is generated with Jekyll.
d189e05 Tom Preston-Werner first commit
mojombo authored
77
3a21a0b Tom Preston-Werner break long lines in readme
mojombo authored
78 The proto-site repo
79 ("http://github.com/mojombo/tpw":http://github.com/mojombo/tpw) is converted
80 into the actual site
81 ("http://tom.preston-werner.com/":http://tom.preston-werner.com)
d189e05 Tom Preston-Werner first commit
mojombo authored
82
b8ce181 Tom Preston-Werner more info in the readme
mojombo authored
83 h2. Install
d189e05 Tom Preston-Werner first commit
mojombo authored
84
b8ce181 Tom Preston-Werner more info in the readme
mojombo authored
85 The best way to install Jekyll is via RubyGems:
86
528a18f Tom Preston-Werner reorganize readme
mojombo authored
87 $ sudo gem install mojombo-jekyll -s http://gems.github.com/
b8ce181 Tom Preston-Werner more info in the readme
mojombo authored
88
0e81edd Mark Reid Added note about dependencies.
mreid authored
89 Jekyll requires the gems `directory_watcher`, `liquid`, `open4`,
5908027 Tom Preston-Werner allow use of rdiscount if --rdiscount is set and gem is installed
mojombo authored
90 and `maruku` (for markdown support). These are automatically
b094b93 Mark Reid Replaced rdiscount with Maruku for Markdown with equation support
mreid authored
91 installed by the gem install command.
92
93 Maruku comes with optional support for LaTeX to PNG rendering via
94 "blahtex":http://gva.noekeon.org/blahtexml/ (Version 0.6) which must be in
95 your $PATH along with `dvips`.
96
97 (NOTE: the version of maruku I am using is `remi-maruku` on GitHub as it
98 does not assume a fixed location for `dvips`.)
0e81edd Mark Reid Added note about dependencies.
mreid authored
99
b8ce181 Tom Preston-Werner more info in the readme
mojombo authored
100 h2. Run
101
102 $ cd /path/to/proto/site
103 $ jekyll
104
3a21a0b Tom Preston-Werner break long lines in readme
mojombo authored
105 This will generate the site and place it in /path/to/proto/site/_site. If
106 you'd like the generated site placed somewhere else:
528a18f Tom Preston-Werner reorganize readme
mojombo authored
107
108 $ jekyll /path/to/place/generated/site
109
110 And if you don't want to be in the proto site root to run Jekyll:
111
112 $ jekyll /path/to/proto/site /path/to/place/generated/site
113
114 h2. Run Options
d6a0227 Tom Preston-Werner update readme with --lsi info
mojombo authored
115
3a21a0b Tom Preston-Werner break long lines in readme
mojombo authored
116 There is an autobuild feature that will regenerate your site if any of the
117 files change. The autobuild feature can be used on any of the invocations:
94bf6de Tom Preston-Werner update readme
mojombo authored
118
119 $ jekyll --auto
120
d6a0227 Tom Preston-Werner update readme with --lsi info
mojombo authored
121 By default, the "related posts" functionality will produce crappy results.
122 In order to get high quality results with a true LSI algorithm, you must
123 enable it (it may take some time to run if you have many posts):
124
125 $ jekyll --lsi
126
3a21a0b Tom Preston-Werner break long lines in readme
mojombo authored
127 For static code highlighting, you can install Pygments (see below) and then
128 use that to make your code blocks look pretty. To activate Pygments support
129 during the conversion:
b8ce181 Tom Preston-Werner more info in the readme
mojombo authored
130
528a18f Tom Preston-Werner reorganize readme
mojombo authored
131 $ jekyll --pygments
b8ce181 Tom Preston-Werner more info in the readme
mojombo authored
132
5908027 Tom Preston-Werner allow use of rdiscount if --rdiscount is set and gem is installed
mojombo authored
133 By default, Jekyll uses "Maruku":http://maruku.rubyforge.org (pure Ruby) for
134 Markdown support. If you'd like to use RDiscount (faster, but requires
135 compilation), you must install it (gem install rdiscount) and then you can
136 have it used instead:
137
138 $ jekyll --rdiscount
6bfaa6b John Reilly updated readme to include --server option
johnreilly authored
139
140 When previewing complex sites locally, simply opening the site in a web
141 browser (using file://) can cause problems with links that are relative to
142 the site root (e.g., "/stylesheets/style.css"). To get around this, Jekyll
8ed84a7 Tom Preston-Werner start server after jekyll processing so webrick has something to serve
mojombo authored
143 can launch a simple WEBrick server (works well in conjunction with --auto).
144 Default port is 4000:
6bfaa6b John Reilly updated readme to include --server option
johnreilly authored
145
8ed84a7 Tom Preston-Werner start server after jekyll processing so webrick has something to serve
mojombo authored
146 $ jekyll --server [PORT]
5908027 Tom Preston-Werner allow use of rdiscount if --rdiscount is set and gem is installed
mojombo authored
147
6b582ff Tom Preston-Werner document liquid data
mojombo authored
148 h2. Data
149
3a21a0b Tom Preston-Werner break long lines in readme
mojombo authored
150 Jekyll traverses your site looking for files to process. Any files with YAML
151 front matter (see below) are subject to processing. For each of these files,
152 Jekyll makes a variety of data available to the pages via the Liquid
153 templating system. The following is a reference of the available data.
0c270cb Tom Preston-Werner better data docs
mojombo authored
154
155 h3. Global
156
157 site
158 Sitewide information.
159
160 page
161 For Posts, this is the union of the data in the YAML front matter and the
162 computed data (such as URL and date). For regular pages, this is just the
163 YAML front matter.
164
165 content
166 In layout files, this contains the content of the subview(s). In Posts or
6de22b3 Tom Preston-Werner small readme cleanup
mojombo authored
167 Pages, this is undefined.
0c270cb Tom Preston-Werner better data docs
mojombo authored
168
6b582ff Tom Preston-Werner document liquid data
mojombo authored
169 h3. Site
170
171 site.time
043fb15 Tom Preston-Werner readme clarifications
mojombo authored
172 The current Time (when you run the jekyll command).
6b582ff Tom Preston-Werner document liquid data
mojombo authored
173
174 site.posts
043fb15 Tom Preston-Werner readme clarifications
mojombo authored
175 A reverse chronological list of all Posts.
6b582ff Tom Preston-Werner document liquid data
mojombo authored
176
d48157c Tom Preston-Werner move related_posts into site data
mojombo authored
177 site.related_posts
178 If the page being processed is a Post, this contains a list of up to ten
043fb15 Tom Preston-Werner readme clarifications
mojombo authored
179 related Posts. By default, these are low quality but fast to compute. For
180 high quality but slow to compute results, run the jekyll command with the
181 --lsi (latent semantic indexing) option.
d48157c Tom Preston-Werner move related_posts into site data
mojombo authored
182
3a8f7a8 Added post categories based on directories containing _posts
Mark Reid authored
183 site.categories.CATEGORY
dad9a31 Tom Preston-Werner fix categories and add topics
mojombo authored
184 The list of all Posts in category CATEGORY.
3a8f7a8 Added post categories based on directories containing _posts
Mark Reid authored
185
6b582ff Tom Preston-Werner document liquid data
mojombo authored
186 h3. Post
187
188 post.title
043fb15 Tom Preston-Werner readme clarifications
mojombo authored
189 The title of the Post.
6b582ff Tom Preston-Werner document liquid data
mojombo authored
190
191 post.url
043fb15 Tom Preston-Werner readme clarifications
mojombo authored
192 The URL of the Post without the domain.
0d18c6b Tom Preston-Werner readme data tweaks
mojombo authored
193 e.g. /2008/12/14/my-post.html
6b582ff Tom Preston-Werner document liquid data
mojombo authored
194
195 post.date
043fb15 Tom Preston-Werner readme clarifications
mojombo authored
196 The Date assigned to the Post.
6b582ff Tom Preston-Werner document liquid data
mojombo authored
197
198 post.id
043fb15 Tom Preston-Werner readme clarifications
mojombo authored
199 An identifier unique to the Post (useful in RSS feeds).
0d18c6b Tom Preston-Werner readme data tweaks
mojombo authored
200 e.g. /2008/12/14/my-post
6b582ff Tom Preston-Werner document liquid data
mojombo authored
201
dad9a31 Tom Preston-Werner fix categories and add topics
mojombo authored
202 post.categories
203 The list of categories to which this post belongs. Categories are
204 derived from the directory structure above the _posts directory. For
205 example, a post at /work/code/_posts/2008-12-24-closures.textile
206 would have this field set to ['work', 'code'].
207
208 post.topics
209 The list of topics for this Post. Topics are derived from the directory
210 structure beneath the _posts directory. For example, a post at
211 /_posts/music/metal/2008-12-24-metalocalypse.textile would have this field
212 set to ['music', 'metal'].
213
6b582ff Tom Preston-Werner document liquid data
mojombo authored
214 post.content
043fb15 Tom Preston-Werner readme clarifications
mojombo authored
215 The content of the Post.
6b582ff Tom Preston-Werner document liquid data
mojombo authored
216
5c46fd6 Tom Preston-Werner document yaml front matter
mojombo authored
217 h2. YAML Front Matter
218
3a21a0b Tom Preston-Werner break long lines in readme
mojombo authored
219 Any files that contain a YAML front matter block will be processed by Jekyll
220 as special files. The front matter must be the first thing in the file and
221 takes the form of:
5c46fd6 Tom Preston-Werner document yaml front matter
mojombo authored
222
8bea61e Tom Preston-Werner fix formatting
mojombo authored
223 <pre>
7716e64 Tom Preston-Werner fix formatting again
mojombo authored
224 ---
225 layout: post
226 title: Blogging Like a Hacker
227 ---
8bea61e Tom Preston-Werner fix formatting
mojombo authored
228 </pre>
5c46fd6 Tom Preston-Werner document yaml front matter
mojombo authored
229
3a21a0b Tom Preston-Werner break long lines in readme
mojombo authored
230 Between the triple-dashed lines, you can set predefined variables (see below
231 for a reference) or custom data of your own.
5c46fd6 Tom Preston-Werner document yaml front matter
mojombo authored
232
233 h3. Predefined Global Variables
234
516afee Tom Preston-Werner fix formatting one more time
mojombo authored
235 layout
236 If set, this specifies the layout file to use. Use the layout file
237 name without file extension. Layout files must be placed in the
238 <code>_layouts</code> directory.
5c46fd6 Tom Preston-Werner document yaml front matter
mojombo authored
239
240 h3. Predefined Post Variables
241
242 permalink
243 If you need your processed URLs to be something other than the default
244 /year/month/day/title.html then you can set this variable and it will
245 be used as the final URL.
246
247 h3. Custom Variables
248
249 Any variables in the front matter that are not predefined are mixed into the
250 data that is sent to the Liquid templating engine during the conversion. For
251 instance, if you set a <code>title</code>, you can use that in your layout to
252 set the page title:
253
7716e64 Tom Preston-Werner fix formatting again
mojombo authored
254 <pre>
255 <title>{{ page.title }}</title>
256 </pre>
5c46fd6 Tom Preston-Werner document yaml front matter
mojombo authored
257
1e9040f Tom Preston-Werner add code highlighting docs to readme
mojombo authored
258 h2. Filters, Tags, and Blocks
259
3a21a0b Tom Preston-Werner break long lines in readme
mojombo authored
260 In addition to the built-in Liquid filters, tags, and blocks, Jekyll provides
261 some additional items that you can use in your site.
1d7b30b Tom Preston-Werner document filters
mojombo authored
262
263 h3. Date to XML Schema (Filter)
264
265 Convert a Time into XML Schema format.
266
267 {{ site.time | date_to_xmlschema }}
268
269 becomes
270
271 2008-11-17T13:07:54-08:00
272
273 h3. XML Escape (Filter)
274
275 Escape some text for use in XML.
276
277 {{ post.content | xml_escape }}
278
279 h3. Number of Words (Filter)
280
281 Count the number of words in some text.
282
283 {{ post.content | number_of_words }}
284
285 becomes
286
287 1337
288
289 h3. Include (Tag)
46169d3 Tom Preston-Werner add include docs to readme
mojombo authored
290
6de22b3 Tom Preston-Werner small readme cleanup
mojombo authored
291 If you have small page fragments that you wish to include in multiple places
292 on your site, you can use the <code>include</code> tag.
46169d3 Tom Preston-Werner add include docs to readme
mojombo authored
293
294 <pre>{% include sig.textile %}</pre>
295
3a21a0b Tom Preston-Werner break long lines in readme
mojombo authored
296 Jekyll expects all include files to be placed in an <code>_includes</code>
297 directory at the root of your source dir. So this will embed the contents of
298 <code>/path/to/proto/site/_includes/sig.textile</code> into the calling file.
46169d3 Tom Preston-Werner add include docs to readme
mojombo authored
299
1d7b30b Tom Preston-Werner document filters
mojombo authored
300 h3. Code Highlighting (Block)
1e9040f Tom Preston-Werner add code highlighting docs to readme
mojombo authored
301
302 Jekyll has built in support for syntax highlighting of over "100
303 languages":http://pygments.org/languages/ via "Pygments":http://pygments.org/.
f57bb07 Tom Preston-Werner remind about --pygments in readme
mojombo authored
304 In order to take advantage of this you'll need to have Pygments installed, and
3a21a0b Tom Preston-Werner break long lines in readme
mojombo authored
305 the pygmentize binary must be in your path. When you run Jekyll, make sure you
306 run it with Pygments support:
f57bb07 Tom Preston-Werner remind about --pygments in readme
mojombo authored
307
308 $ jekyll --pygments
1e9040f Tom Preston-Werner add code highlighting docs to readme
mojombo authored
309
310 To denote a code block that should be highlighted:
311
312 <pre>
313 {% highlight ruby %}
314 def foo
315 puts 'foo'
316 end
317 {% endhighlight %}
318 </pre>
319
320 The argument to <code>highlight</code> is the language identifier. To find the
321 appropriate identifier to use for your favorite language, look for the "short
322 name" on the "Lexers":http://pygments.org/docs/lexers/ page.
323
324 In order for the highlighting to show up, you'll need to include a
325 highlighting stylesheet. For an example stylesheet you can look at
326 "syntax.css":http://github.com/mojombo/tpw/tree/master/css/syntax.css. These
327 are the same styles as used by GitHub and you are free to use them for your
328 own site.
329
3a8f7a8 Added post categories based on directories containing _posts
Mark Reid authored
330 h2. Categories
331
332 Posts are placed into categories based on the directory structure they are found
333 within (see above for an example). The categories can be accessed from within
334 a Liquid template as follows:
335
336 <pre>
337 {% for post in site.categories.foo %}
338 <li><span>{{ post.date | date_to_string }}</span> - {{ post.title }}</li>
339 {% endfor %}
340 </pre>
341
342 This would list all the posts in the category 'foo' by date and title.
343
344 The posts within each category are sorted in reverse chronological order.
345
b8ce181 Tom Preston-Werner more info in the readme
mojombo authored
346 h2. Contribute
347
348 If you'd like to hack on Jekyll, grab the source from GitHub. To get
349 all of the dependencies, install the gem first.
d189e05 Tom Preston-Werner first commit
mojombo authored
350
bffdeee Tom Preston-Werner rename to Jekyll
mojombo authored
351 $ git clone git://github.com/mojombo/jekyll
b8ce181 Tom Preston-Werner more info in the readme
mojombo authored
352
353 The best way to get your changes merged back into core is as follows:
354
31aa865 Tom Preston-Werner proper list syntax
mojombo authored
355 # Fork mojombo/jekyll on GitHub
356 # Clone down your fork
357 # Create a topic branch to contain your change
358 # Hack away
94bf6de Tom Preston-Werner update readme
mojombo authored
359 # Do not change the version number, I will do that on my end
31aa865 Tom Preston-Werner proper list syntax
mojombo authored
360 # If necessary, rebase your commits into logical chunks, without errors
361 # Push the branch up to GitHub
94bf6de Tom Preston-Werner update readme
mojombo authored
362 # Send me (mojombo) a pull request for your branch
d189e05 Tom Preston-Werner first commit
mojombo authored
363
8477cb5 Nick Gerakines Adding Movable Type migration library to lib/jekyll/converters/.
ngerakines authored
364 h2. Blog migrations
365
366 h3. Movable Type
367
368 To migrate your MT blog into Jekyll, you'll need read access to the database.
369 The lib/jekyll/converters/mt.rb module provides a simple convert to create
370 .markdown files in a _posts directory based on the entries contained therein.
371
372 $ export DB=my_mtdb
373 $ export USER=dbuser
374 $ export PASS=dbpass
375 $ ruby -r './lib/jekyll/converters/mt' -e 'Jekyll::MT.process( \
376 "#{ENV["DB"]}", "#{ENV["USER"]}", "#{ENV["PASS"]}")'
377
378 You may need to adjust the SQL query used to retrieve MT entries. Left alone,
379 it will attempt to pull all entries across all blogs regardless of status.
380 Please check the results and verify the posts before publishing.
381
574637a Tom Preston-Werner flesh out readme a little bit
mojombo authored
382 h2. License
d189e05 Tom Preston-Werner first commit
mojombo authored
383
384 (The MIT License)
385
574637a Tom Preston-Werner flesh out readme a little bit
mojombo authored
386 Copyright (c) 2008 Tom Preston-Werner
d189e05 Tom Preston-Werner first commit
mojombo authored
387
388 Permission is hereby granted, free of charge, to any person obtaining
389 a copy of this software and associated documentation files (the
390 'Software'), to deal in the Software without restriction, including
391 without limitation the rights to use, copy, modify, merge, publish,
392 distribute, sublicense, and/or sell copies of the Software, and to
393 permit persons to whom the Software is furnished to do so, subject to
394 the following conditions:
395
396 The above copyright notice and this permission notice shall be
397 included in all copies or substantial portions of the Software.
398
399 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
400 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
401 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
402 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
403 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
404 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
405 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.