Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 650 lines (468 sloc) 23.112 kb
bffdeee @mojombo rename to Jekyll
mojombo authored
1 h1. Jekyll
d189e05 @mojombo first commit
mojombo authored
2
1324535 @mojombo update readme for new workflow
mojombo authored
3 By Tom Preston-Werner, Nick Quaranto, and many awesome contributors!
4
5 h2. Description
6
3a21a0b @mojombo break long lines in readme
mojombo authored
7 Jekyll is a simple, blog aware, static site generator. It takes a template
8 directory (representing the raw form of a website), runs it through Textile or
9 Markdown and Liquid converters, and spits out a complete, static website
10 suitable for serving with Apache or your favorite web server. Visit
11 "http://tom.preston-werner.com":http://tom.preston-werner.com to see an
12 example of a Jekyll generated blog.
13
14 To understand how this all works, open up my
15 "TPW":http://github.com/mojombo/tpw repo in a new browser window. I'll be
16 referencing the code there.
17
18 Take a look at
19 "index.html":http://github.com/mojombo/tpw/tree/master/index.html. This file
20 represents the homepage of the site. At the top of the file is a chunk of YAML
21 that contains metadata about the file. This data tells Jekyll what layout to
22 give the file, what the page's title should be, etc. In this case, I specify
23 that the "default" template should be used. You can find the layout files in
24 the "_layouts":http://github.com/mojombo/tpw/tree/master/_layouts directory.
25 If you open
26 "default.html":http://github.com/mojombo/tpw/tree/master/_layouts/default.html
27 you can see that the homepage is constructed by wrapping index.html with this
28 layout.
29
30 You'll also notice Liquid templating code in these files.
31 "Liquid":http://www.liquidmarkup.org/ is a simple, extensible templating
32 language that makes it easy to embed data in your templates. For my homepage I
33 wanted to have a list of all my blog posts. Jekyll hands me a Hash containing
34 various data about my site. A reverse chronological list of all my blog posts
35 can be found in <code>site.posts</code>. Each post, in turn, contains various
36 fields such as <code>title</code> and <code>date</code>.
37
3a8f7a8 Added post categories based on directories containing _posts
Mark Reid authored
38 Jekyll gets the list of blog posts by parsing the files in any
39 "_posts":http://github.com/mojombo/tpw/tree/master/_posts directory found in
40 subdirectories below the root.
0b78c32 @mreid Added option to not put file date in permalink URL
mreid authored
41 Each post's filename contains (by default) the publishing date and slug (what shows up in the
3a21a0b @mojombo break long lines in readme
mojombo authored
42 URL) that the final HTML file should have. Open up the file corresponding to a
43 blog post:
44 "2008-11-17-blogging-like-a-hacker.textile":http://github.com/mojombo/tpw/tree/master/_posts/2008-11-17-blogging-like-a-hacker.textile.
45 GitHub renders textile files by default, so to better understand the file,
46 click on the
47 "raw":http://github.com/mojombo/tpw/tree/master/_posts/2008-11-17-blogging-like-a-hacker.textile?raw=true
48 view to see the original file. Here I've specified the <code>post</code>
49 layout. If you look at that file you'll see an example of a nested layout.
50 Layouts can contain other layouts allowing you a great deal of flexibility in
51 how pages are assembled. In my case I use a nested layout in order to show
52 related posts for each blog entry. The YAML also specifies the post's title
53 which is then embedded in the post's body via Liquid.
54
55 Posts are handled in a special way by Jekyll. The date you specify in the
56 filename is used to construct the URL in the generated site. The example post,
57 for instance, ends up at
58 <code>http://tom.preston-werner.com/2008/11/17/blogging-like-a-hacker.html</code>.
59
eb41a06 @henrik Post time (not just date) can be specified in slug or YAML block. Liq…
henrik authored
60 Jekyll also supports specifying the post time in the filename. The format is e.g.
61 '2009-04-13_23-45-my-post.html'. Note that the time is prefixed by an underscore,
62 not a dash, so post slugs starting with numbers won't be parsed incorrectly.
63 Times in the filename must be on a 24-hour clock. Times and dates are treated by
64 Jekyll as local time.
65
dad9a31 @mojombo fix categories and add topics
mojombo authored
66 Categories for posts are derived from the directory structure the posts were
67 found within. A post that appears in the directory foo/bar/_posts is placed in
68 the categories 'foo' and 'bar'. By selecting posts from particular categories
69 in your Liquid templates, you will be able to host multiple blogs within a
70 site.
3a8f7a8 Added post categories based on directories containing _posts
Mark Reid authored
71
3a21a0b @mojombo break long lines in readme
mojombo authored
72 Files that do not reside in directories prefixed with an underscore are
73 mirrored into a corresponding directory structure in the generated site. If a
74 file does not have a YAML preface, it is not run through the Liquid
75 interpreter. Binary files are copied over unmodified.
76
77 Jekyll is still a very young project. I've only developed the exact
78 functionality that I've needed. As time goes on I'd like to see the project
79 mature and support additional features. If you end up using Jekyll for your
80 own blog, drop me a line and let me know what you'd like to see in future
81 versions. Better yet, fork the project over at GitHub and hack in the features
82 yourself!
d189e05 @mojombo first commit
mojombo authored
83
574637a @mojombo flesh out readme a little bit
mojombo authored
84 h2. Example Proto-Site
d189e05 @mojombo first commit
mojombo authored
85
bffdeee @mojombo rename to Jekyll
mojombo authored
86 My own personal site/blog is generated with Jekyll.
d189e05 @mojombo first commit
mojombo authored
87
3a21a0b @mojombo break long lines in readme
mojombo authored
88 The proto-site repo
89 ("http://github.com/mojombo/tpw":http://github.com/mojombo/tpw) is converted
90 into the actual site
91 ("http://tom.preston-werner.com/":http://tom.preston-werner.com)
d189e05 @mojombo first commit
mojombo authored
92
b8ce181 @mojombo more info in the readme
mojombo authored
93 h2. Install
d189e05 @mojombo first commit
mojombo authored
94
b8ce181 @mojombo more info in the readme
mojombo authored
95 The best way to install Jekyll is via RubyGems:
96
528a18f @mojombo reorganize readme
mojombo authored
97 $ sudo gem install mojombo-jekyll -s http://gems.github.com/
b8ce181 @mojombo more info in the readme
mojombo authored
98
0e81edd @mreid Added note about dependencies.
mreid authored
99 Jekyll requires the gems `directory_watcher`, `liquid`, `open4`,
5908027 @mojombo allow use of rdiscount if --rdiscount is set and gem is installed
mojombo authored
100 and `maruku` (for markdown support). These are automatically
b094b93 @mreid Replaced rdiscount with Maruku for Markdown with equation support
mreid authored
101 installed by the gem install command.
102
103 Maruku comes with optional support for LaTeX to PNG rendering via
104 "blahtex":http://gva.noekeon.org/blahtexml/ (Version 0.6) which must be in
105 your $PATH along with `dvips`.
106
107 (NOTE: the version of maruku I am using is `remi-maruku` on GitHub as it
108 does not assume a fixed location for `dvips`.)
0e81edd @mreid Added note about dependencies.
mreid authored
109
b8ce181 @mojombo more info in the readme
mojombo authored
110 h2. Run
111
112 $ cd /path/to/proto/site
113 $ jekyll
114
3a21a0b @mojombo break long lines in readme
mojombo authored
115 This will generate the site and place it in /path/to/proto/site/_site. If
116 you'd like the generated site placed somewhere else:
528a18f @mojombo reorganize readme
mojombo authored
117
118 $ jekyll /path/to/place/generated/site
119
120 And if you don't want to be in the proto site root to run Jekyll:
121
122 $ jekyll /path/to/proto/site /path/to/place/generated/site
123
124 h2. Run Options
d6a0227 @mojombo update readme with --lsi info
mojombo authored
125
86e72a8 @mojombo a few style changes and readme for pretty permalink
mojombo authored
126 h3. Autobuild
127
3a21a0b @mojombo break long lines in readme
mojombo authored
128 There is an autobuild feature that will regenerate your site if any of the
129 files change. The autobuild feature can be used on any of the invocations:
94bf6de @mojombo update readme
mojombo authored
130
131 $ jekyll --auto
132
86e72a8 @mojombo a few style changes and readme for pretty permalink
mojombo authored
133 h3. Related Posts
134
d6a0227 @mojombo update readme with --lsi info
mojombo authored
135 By default, the "related posts" functionality will produce crappy results.
136 In order to get high quality results with a true LSI algorithm, you must
137 enable it (it may take some time to run if you have many posts):
138
139 $ jekyll --lsi
140
86e72a8 @mojombo a few style changes and readme for pretty permalink
mojombo authored
141 h3. Code Highlighting
142
3a21a0b @mojombo break long lines in readme
mojombo authored
143 For static code highlighting, you can install Pygments (see below) and then
144 use that to make your code blocks look pretty. To activate Pygments support
145 during the conversion:
b8ce181 @mojombo more info in the readme
mojombo authored
146
528a18f @mojombo reorganize readme
mojombo authored
147 $ jekyll --pygments
e4c7dcf @henrik Option to cache Pygments output for faster re-rendering.
henrik authored
148
149 Highlighting a blog post can take a second or two, and with a lot of posts,
150 it adds up. You can tell Jekyll to cache pygments output in a directory for
151 faster re-rendering:
152
153 $ jekyll --pygments-cache [PATH]
b8ce181 @mojombo more info in the readme
mojombo authored
154
86e72a8 @mojombo a few style changes and readme for pretty permalink
mojombo authored
155 h3. Markdown Processor
156
5908027 @mojombo allow use of rdiscount if --rdiscount is set and gem is installed
mojombo authored
157 By default, Jekyll uses "Maruku":http://maruku.rubyforge.org (pure Ruby) for
158 Markdown support. If you'd like to use RDiscount (faster, but requires
159 compilation), you must install it (gem install rdiscount) and then you can
160 have it used instead:
161
162 $ jekyll --rdiscount
56e1707 @henrik Sass support.
henrik authored
163
164 h3. Sass
165
166 To transform all ".sass":http://github.com/nex3/haml/tree/master
167 files anywhere in your file tree to CSS (e.g. '/css/site.sass' will
168 generate '/css/site.css'):
169
170 $ jekyll --sass
67c5905 @henrik Option to enable Haml (without suppress_eval) in posts and pages (but…
henrik authored
171
172 h3. Haml
173
174 To transform ".haml":http://github.com/nex3/haml/tree/master files to HTML
175 (e.g. '/about.haml' will generate '/about.html'):
176
177 $ jekyll --haml
178
15f0383 @henrik Basic support for Haml layouts.
henrik authored
179 Note that pages and posts must have a YAML metadata block at the top to be
180 converted. Layouts don't need to.
67c5905 @henrik Option to enable Haml (without suppress_eval) in posts and pages (but…
henrik authored
181
182 Haml content is intentionally not filtered, so you can use any Ruby code.
86e72a8 @mojombo a few style changes and readme for pretty permalink
mojombo authored
183
b9dea95 @henrik Allow _helpers.rb in blogs to provide custom Haml helpers. Document t…
henrik authored
184 If you want to define methods you can call from your Haml files, create
185 a _helpers.rb file in the root of your blog and put the methods there,
186 inside a module named Helpers.
187
188 Jekyll provides some helpers out of the box:
189
190 h(string)
191 HTML entity-escapes the input string.
192
193 link_to(text, url)
194 Creates a link to the URL with the linked text (or markup).
195
86e72a8 @mojombo a few style changes and readme for pretty permalink
mojombo authored
196 h3. Local Server
197
6bfaa6b @johnreilly updated readme to include --server option
johnreilly authored
198 When previewing complex sites locally, simply opening the site in a web
199 browser (using file://) can cause problems with links that are relative to
200 the site root (e.g., "/stylesheets/style.css"). To get around this, Jekyll
8ed84a7 @mojombo start server after jekyll processing so webrick has something to serve
mojombo authored
201 can launch a simple WEBrick server (works well in conjunction with --auto).
202 Default port is 4000:
6bfaa6b @johnreilly updated readme to include --server option
johnreilly authored
203
8ed84a7 @mojombo start server after jekyll processing so webrick has something to serve
mojombo authored
204 $ jekyll --server [PORT]
5908027 @mojombo allow use of rdiscount if --rdiscount is set and gem is installed
mojombo authored
205
86e72a8 @mojombo a few style changes and readme for pretty permalink
mojombo authored
206 h3. Permalink Style
207
0b78c32 @mreid Added option to not put file date in permalink URL
mreid authored
208 By default, the permalink for each post begins with its date in 'YYYY/MM/DD'
86e72a8 @mojombo a few style changes and readme for pretty permalink
mojombo authored
209 format.
210
211 If you do not wish to have the date appear in the URL of each post,
0b78c32 @mreid Added option to not put file date in permalink URL
mreid authored
212 you can change the permalink style to 'none' so that only the 'slug' part of
213 the filename is used. For example, with the permalink style set to 'none' the
214 file '2009-01-01-happy-new-year.markdown' will have a permalink like
215 'http://yoursite.com/happy-new-year.html'. The date of the post will still be
216 read from the filename (and is required!) to be used elsewhere in Jekyll.
217
86e72a8 @mojombo a few style changes and readme for pretty permalink
mojombo authored
218 If you want WordPress-style pretty URLs that leave off the .html, you can
219 change the permalink style to 'pretty' and directories corresponding to the
220 date parts and post name will be made and an index.html will be placed in the
221 leaf directory resulting in URLs like 2008/11/17/blogging-like-a-hacker/.
222
223 $ jekyll --permalink [date|none|pretty]
1d42b39 @henrik --multiviews flag to not use .html in post links. For use with Apache…
henrik authored
224
225 Another way to leave off the .html is to configure Apache with 'Options +MultiViews'.
226 Just link to pages without the extension (and without a trailing slash, like '/about').
227 Then tell Jekyll not to add '.html' when linking to blog posts, like so:
228
229 $ jekyll --multiviews
230
231 Note that this has no effect with '--permalink pretty' since that makes an index.html
232 file in a directory.
0b78c32 @mreid Added option to not put file date in permalink URL
mreid authored
233
6fec047 Added ability to set Jekyll parameters via _config.yaml file
Mark authored
234 h2. Configuration File
235
236 All of the options listed above can be specified on a site-by-site basis in
73d42b2 @mojombo Huge refactor to move all config into Jekyll::Site
mojombo authored
237 a '_config.yml' file at the root of the site's source. As the filename
6fec047 Added ability to set Jekyll parameters via _config.yaml file
Mark authored
238 suggests, the configuration is given in "YAML":http://www.yaml.org/. As
239 well as all of the options discussed in the last section, there are a few
240 additional options:
241
242 destination: [PATH] # Specify where the site should be rendered
243 markdown: [maruku|rdiscount] # Which markdown renderer to use?
244
245 maruku: # This is a YAML hash for Maruku settings
246 use_divs: [BOOLEAN] # Use the div element Maruku extension
247 use_tex: [BOOLEAN] # Use the LaTeX extension to Maruku
248 png_dir: [PATH] # Where should the math PNGs be stored?
249 png_url: [URL] # A relative URL for the PNGs
250
251 The default configuration is shown below as in YAML format:
252
253 destination: ./_site
254 auto: false
255 lsi: false
256 server_port: 4000
257 pygments: false
258 markdown: maruku
259 permalink: date
260
261 maruku:
262 use_tex: false
263 use_divs: false
264 png_dir: images/latex
265 png_url: /images/latex
266
267 Parameters set in a configuration file override the default values. Parameters
268 set using command line options override both the default values and those set
269 in a configuration file.
270
77bf31c @henrik Support post_defaults section in _config.yml, typically used to set a…
henrik authored
271 Additionally, you can set defaults for the post data blocks. For example, you
272 can set the default layout for posts, so you don't have to specify it in every
273 post:
274
275 post_defaults:
276 layout: post
277
278 Any values set in the actual post will override these defaults.
279
6b582ff @mojombo document liquid data
mojombo authored
280 h2. Data
281
3a21a0b @mojombo break long lines in readme
mojombo authored
282 Jekyll traverses your site looking for files to process. Any files with YAML
283 front matter (see below) are subject to processing. For each of these files,
15f0383 @henrik Basic support for Haml layouts.
henrik authored
284 Jekyll makes a variety of data available to the pages via Haml or the Liquid
285 Liquid templating system. The following is a reference of the available data.
0c270cb @mojombo better data docs
mojombo authored
286
287 h3. Global
288
289 site
290 Sitewide information.
291
292 page
293 For Posts, this is the union of the data in the YAML front matter and the
294 computed data (such as URL and date). For regular pages, this is just the
295 YAML front matter.
296
297 content
298 In layout files, this contains the content of the subview(s). In Posts or
6de22b3 @mojombo small readme cleanup
mojombo authored
299 Pages, this is undefined.
0c270cb @mojombo better data docs
mojombo authored
300
6b582ff @mojombo document liquid data
mojombo authored
301 h3. Site
302
303 site.time
043fb15 @mojombo readme clarifications
mojombo authored
304 The current Time (when you run the jekyll command).
6b582ff @mojombo document liquid data
mojombo authored
305
306 site.posts
043fb15 @mojombo readme clarifications
mojombo authored
307 A reverse chronological list of all Posts.
5ec47ed @henrik site.collated_posts for use with archives.
henrik authored
308
309 site.collated_posts
310 A nested hash by year, then month number, then day, then a list of Posts.
311 Suitable for post archives. You probably need to show these with Haml
312 since Liquid is too limited. For example:
313 - site.collated_posts.sort.reverse.each do |year,months|
314 %h2= year
315 - months.sort.reverse.each do |month,days|
316 %h3= Date::MONTHNAMES[month]
317 - days.sort.reverse.each do |day,posts|
318 %ol
319 - posts.each do |post|
320 %li
321 %strong= "#{day}:"
322 = link_to(h(post.title), post.url)
6b582ff @mojombo document liquid data
mojombo authored
323
d48157c @mojombo move related_posts into site data
mojombo authored
324 site.related_posts
325 If the page being processed is a Post, this contains a list of up to ten
043fb15 @mojombo readme clarifications
mojombo authored
326 related Posts. By default, these are low quality but fast to compute. For
327 high quality but slow to compute results, run the jekyll command with the
328 --lsi (latent semantic indexing) option.
d48157c @mojombo move related_posts into site data
mojombo authored
329
3a8f7a8 Added post categories based on directories containing _posts
Mark Reid authored
330 site.categories.CATEGORY
dad9a31 @mojombo fix categories and add topics
mojombo authored
331 The list of all Posts in category CATEGORY.
3a8f7a8 Added post categories based on directories containing _posts
Mark Reid authored
332
072d9e7 @henrik Add tag support. Like categories or topics but not reflected in the U…
henrik authored
333 site.tags.TAG
334 The list of all Posts tagged TAG.
335
6b582ff @mojombo document liquid data
mojombo authored
336 h3. Post
337
338 post.title
043fb15 @mojombo readme clarifications
mojombo authored
339 The title of the Post.
6b582ff @mojombo document liquid data
mojombo authored
340
341 post.url
043fb15 @mojombo readme clarifications
mojombo authored
342 The URL of the Post without the domain.
0d18c6b @mojombo readme data tweaks
mojombo authored
343 e.g. /2008/12/14/my-post.html
6b582ff @mojombo document liquid data
mojombo authored
344
345 post.date
eb41a06 @henrik Post time (not just date) can be specified in slug or YAML block. Liq…
henrik authored
346 The Date (actually a Time object) assigned to the Post.
6b582ff @mojombo document liquid data
mojombo authored
347
348 post.id
043fb15 @mojombo readme clarifications
mojombo authored
349 An identifier unique to the Post (useful in RSS feeds).
0d18c6b @mojombo readme data tweaks
mojombo authored
350 e.g. /2008/12/14/my-post
6b582ff @mojombo document liquid data
mojombo authored
351
dad9a31 @mojombo fix categories and add topics
mojombo authored
352 post.categories
353 The list of categories to which this post belongs. Categories are
354 derived from the directory structure above the _posts directory. For
355 example, a post at /work/code/_posts/2008-12-24-closures.textile
356 would have this field set to ['work', 'code'].
357
358 post.topics
359 The list of topics for this Post. Topics are derived from the directory
360 structure beneath the _posts directory. For example, a post at
361 /_posts/music/metal/2008-12-24-metalocalypse.textile would have this field
362 set to ['music', 'metal'].
363
072d9e7 @henrik Add tag support. Like categories or topics but not reflected in the U…
henrik authored
364 post.tags
365 The list of tags on this post. Tags are much like topics, but can only be
366 specified in the YAML part of a post, and are not reflected in the URL.
367
6b582ff @mojombo document liquid data
mojombo authored
368 post.content
043fb15 @mojombo readme clarifications
mojombo authored
369 The content of the Post.
6b582ff @mojombo document liquid data
mojombo authored
370
5c46fd6 @mojombo document yaml front matter
mojombo authored
371 h2. YAML Front Matter
372
3a21a0b @mojombo break long lines in readme
mojombo authored
373 Any files that contain a YAML front matter block will be processed by Jekyll
374 as special files. The front matter must be the first thing in the file and
375 takes the form of:
5c46fd6 @mojombo document yaml front matter
mojombo authored
376
8bea61e @mojombo fix formatting
mojombo authored
377 <pre>
7716e64 @mojombo fix formatting again
mojombo authored
378 ---
379 layout: post
380 title: Blogging Like a Hacker
381 ---
8bea61e @mojombo fix formatting
mojombo authored
382 </pre>
5c46fd6 @mojombo document yaml front matter
mojombo authored
383
3a21a0b @mojombo break long lines in readme
mojombo authored
384 Between the triple-dashed lines, you can set predefined variables (see below
385 for a reference) or custom data of your own.
5c46fd6 @mojombo document yaml front matter
mojombo authored
386
387 h3. Predefined Global Variables
388
516afee @mojombo fix formatting one more time
mojombo authored
389 layout
390 If set, this specifies the layout file to use. Use the layout file
391 name without file extension. Layout files must be placed in the
392 <code>_layouts</code> directory.
77bf31c @henrik Support post_defaults section in _config.yml, typically used to set a…
henrik authored
393
394 A default layout for posts can be set in the configuration file.
395 See above.
5c46fd6 @mojombo document yaml front matter
mojombo authored
396
397 h3. Predefined Post Variables
398
399 permalink
400 If you need your processed URLs to be something other than the default
401 /year/month/day/title.html then you can set this variable and it will
402 be used as the final URL.
403
45b33f7 @qrush Adding explanations for new YAML front matter options
qrush authored
404 published
60709da @qrush Removing some bad formatting in the README
qrush authored
405 Set to false if you don't want a post to show up when the site is
406 generated.
eb41a06 @henrik Post time (not just date) can be specified in slug or YAML block. Liq…
henrik authored
407
408 time
409 If you want posts to have a time, you can set this to e.g. '23:45' or
410 '11:45 pm'. This overrides any time specified in the filename like
411 '2009-04-12_23-44-my-post.html'. Note that you must quote the time:
412 time: "23:45"
45b33f7 @qrush Adding explanations for new YAML front matter options
qrush authored
413
60709da @qrush Removing some bad formatting in the README
qrush authored
414 category/categories
415 Instead of placing posts inside of folders, you can specify one or more
416 categories that the post belongs to. When the site is generated the post
417 will act as though it had been set with these categories normally.
45b33f7 @qrush Adding explanations for new YAML front matter options
qrush authored
418
072d9e7 @henrik Add tag support. Like categories or topics but not reflected in the U…
henrik authored
419 tags
420 Similar to categories and topics but not reflected in the URL.
421
5c46fd6 @mojombo document yaml front matter
mojombo authored
422 h3. Custom Variables
423
424 Any variables in the front matter that are not predefined are mixed into the
425 data that is sent to the Liquid templating engine during the conversion. For
426 instance, if you set a <code>title</code>, you can use that in your layout to
427 set the page title:
428
7716e64 @mojombo fix formatting again
mojombo authored
429 <pre>
430 <title>{{ page.title }}</title>
431 </pre>
5c46fd6 @mojombo document yaml front matter
mojombo authored
432
1e9040f @mojombo add code highlighting docs to readme
mojombo authored
433 h2. Filters, Tags, and Blocks
434
3a21a0b @mojombo break long lines in readme
mojombo authored
435 In addition to the built-in Liquid filters, tags, and blocks, Jekyll provides
436 some additional items that you can use in your site.
1d7b30b @mojombo document filters
mojombo authored
437
438 h3. Date to XML Schema (Filter)
439
440 Convert a Time into XML Schema format.
441
442 {{ site.time | date_to_xmlschema }}
443
444 becomes
445
446 2008-11-17T13:07:54-08:00
447
448 h3. XML Escape (Filter)
449
450 Escape some text for use in XML.
451
452 {{ post.content | xml_escape }}
453
454 h3. Number of Words (Filter)
455
456 Count the number of words in some text.
457
458 {{ post.content | number_of_words }}
459
460 becomes
461
462 1337
463
9214762 @mojombo document array_to_sentence_string
mojombo authored
464 h3. Array to Sentence String
465
466 Convert an array into a sentence.
467
468 {{ page.tags | array_to_sentence_string }}
469
470 becomes
471
472 foo, bar, and baz
ee65dad @willcodeforfoo Add textilize filter for transforming input into HTML via RedCloth, s…
willcodeforfoo authored
473
474 h3. Textilize
475
476 Convert a Textile-formatted string into HTML, formatted via RedCloth
477
478 {{ page.excerpt | textilize }}
9214762 @mojombo document array_to_sentence_string
mojombo authored
479
1d7b30b @mojombo document filters
mojombo authored
480 h3. Include (Tag)
46169d3 @mojombo add include docs to readme
mojombo authored
481
6de22b3 @mojombo small readme cleanup
mojombo authored
482 If you have small page fragments that you wish to include in multiple places
483 on your site, you can use the <code>include</code> tag.
46169d3 @mojombo add include docs to readme
mojombo authored
484
485 <pre>{% include sig.textile %}</pre>
486
3a21a0b @mojombo break long lines in readme
mojombo authored
487 Jekyll expects all include files to be placed in an <code>_includes</code>
488 directory at the root of your source dir. So this will embed the contents of
489 <code>/path/to/proto/site/_includes/sig.textile</code> into the calling file.
46169d3 @mojombo add include docs to readme
mojombo authored
490
1d7b30b @mojombo document filters
mojombo authored
491 h3. Code Highlighting (Block)
1e9040f @mojombo add code highlighting docs to readme
mojombo authored
492
493 Jekyll has built in support for syntax highlighting of over "100
494 languages":http://pygments.org/languages/ via "Pygments":http://pygments.org/.
f57bb07 @mojombo remind about --pygments in readme
mojombo authored
495 In order to take advantage of this you'll need to have Pygments installed, and
3a21a0b @mojombo break long lines in readme
mojombo authored
496 the pygmentize binary must be in your path. When you run Jekyll, make sure you
497 run it with Pygments support:
f57bb07 @mojombo remind about --pygments in readme
mojombo authored
498
499 $ jekyll --pygments
1e9040f @mojombo add code highlighting docs to readme
mojombo authored
500
501 To denote a code block that should be highlighted:
502
503 <pre>
504 {% highlight ruby %}
505 def foo
506 puts 'foo'
507 end
508 {% endhighlight %}
509 </pre>
510
511 The argument to <code>highlight</code> is the language identifier. To find the
512 appropriate identifier to use for your favorite language, look for the "short
513 name" on the "Lexers":http://pygments.org/docs/lexers/ page.
514
9b02059 @mojombo couple of tweaks to line numbering option
mojombo authored
515 There is a second argument to <code>highlight</code> called
516 <code>linenos</code> that is optional. Including the <code>linenos</code>
517 argument will force the highlighted code to include line numbers. For
518 instance, the following code block would include line numbers next to each
519 line:
d63f1f9 @jcon Added line number capabilities to highlight blocks
jcon authored
520
521 <pre>
522 {% highlight ruby linenos %}
523 def foo
524 puts 'foo'
525 end
526 {% endhighlight %}
527 </pre>
528
1e9040f @mojombo add code highlighting docs to readme
mojombo authored
529 In order for the highlighting to show up, you'll need to include a
530 highlighting stylesheet. For an example stylesheet you can look at
531 "syntax.css":http://github.com/mojombo/tpw/tree/master/css/syntax.css. These
532 are the same styles as used by GitHub and you are free to use them for your
9b02059 @mojombo couple of tweaks to line numbering option
mojombo authored
533 own site. If you use linenos, you might want to include an additional CSS
534 class definition for <code>lineno</code> in syntax.css to distinguish the line
535 numbers from the highlighted code.
1e9040f @mojombo add code highlighting docs to readme
mojombo authored
536
3a8f7a8 Added post categories based on directories containing _posts
Mark Reid authored
537 h2. Categories
538
9b02059 @mojombo couple of tweaks to line numbering option
mojombo authored
539 Posts are placed into categories based on the directory structure they are
540 found within (see above for an example). The categories can be accessed from
541 within a Liquid template as follows:
3a8f7a8 Added post categories based on directories containing _posts
Mark Reid authored
542
543 <pre>
544 {% for post in site.categories.foo %}
60709da @qrush Removing some bad formatting in the README
qrush authored
545 <li><span>{{ post.date | date_to_string }}</span> - {{ post.title }}</li>
3a8f7a8 Added post categories based on directories containing _posts
Mark Reid authored
546 {% endfor %}
547 </pre>
548
549 This would list all the posts in the category 'foo' by date and title.
550
551 The posts within each category are sorted in reverse chronological order.
552
072d9e7 @henrik Add tag support. Like categories or topics but not reflected in the U…
henrik authored
553 h2. Tags
554
555 Tags are like categories or topics but not reflected in the URL.
556
8477cb5 @ngerakines Adding Movable Type migration library to lib/jekyll/converters/.
ngerakines authored
557 h2. Blog migrations
558
559 h3. Movable Type
560
561 To migrate your MT blog into Jekyll, you'll need read access to the database.
562 The lib/jekyll/converters/mt.rb module provides a simple convert to create
563 .markdown files in a _posts directory based on the entries contained therein.
564
565 $ export DB=my_mtdb
566 $ export USER=dbuser
567 $ export PASS=dbpass
568 $ ruby -r './lib/jekyll/converters/mt' -e 'Jekyll::MT.process( \
569 "#{ENV["DB"]}", "#{ENV["USER"]}", "#{ENV["PASS"]}")'
570
571 You may need to adjust the SQL query used to retrieve MT entries. Left alone,
572 it will attempt to pull all entries across all blogs regardless of status.
573 Please check the results and verify the posts before publishing.
574
e0e7bf1 @codeslinger added Typo 4+ conversion module and docs
codeslinger authored
575 h3. Typo 4+
576
577 To migrate your Typo blog into Jekyll, you'll need read access to the MySQL
578 database. The lib/jekyll/converters/typo.rb module provides a simple convert
579 to create .html, .textile, or .markdown files in a _posts directory based on
580 the entries contained therein.
581
582 $ export DB=my_typo_db
583 $ export USER=dbuser
584 $ export PASS=dbpass
585 $ ruby -r './lib/jekyll/converters/typo' -e 'Jekyll::Typo.process( \
586 "#{ENV["DB"]}", "#{ENV["USER"]}", "#{ENV["PASS"]}")'
587
588 You may need to adjust the code used to filter Typo entries. Left alone,
589 it will attempt to pull all entries across all blogs that were published.
590 This code also has only been tested with Typo version 4+. Previous versions
591 of Typo may not convert correctly. Please check the results and verify the
592 posts before publishing.
593
32a9b6b @PerfectlyNormal created a converter for textpattern, and a simple usage guide
PerfectlyNormal authored
594 h3. TextPattern 4
595
596 To migrate your TextPattern blog into Jekyll, you'll need read access to the MySQL
597 database. The lib/jekyll/converters/textpattern.rb module provides a simple convert to create .textile files in a _posts directory based on
598 the entries contained therein.
599
600 $ ruby -r './lib/jekyll/converters/textpattern' -e 'Jekyll::TextPattern.process( \
601 "database_name", "username", "password", "hostname")'
602
603 The hostname defaults to _localhost_, all other variables are needed
604 You may need to adjust the code used to filter entries. Left alone,
605 it will attempt to pull all entries that are live or sticky.
606
fae0928 @mojombo refine and move contribution section of readme to bottom
mojombo authored
607 h2. Contribute
608
609 If you'd like to hack on Jekyll, start by forking my repo on GitHub:
610
611 http://github.com/mojombo/jekyll
612
613 To get all of the dependencies, install the gem first. The best way to get
614 your changes merged back into core is as follows:
615
616 # Clone down your fork
617 # Create a topic branch to contain your change
618 # Hack away
619 # Add tests and make sure everything still passes by running `rake`
620 # If you are adding new functionality, document it in README.textile
621 # Do not change the version number, I will do that on my end
622 # If necessary, rebase your commits into logical chunks, without errors
623 # Push the branch up to GitHub
1324535 @mojombo update readme for new workflow
mojombo authored
624 # Create an issue on mojombo/grit with a description and link to your branch
fae0928 @mojombo refine and move contribution section of readme to bottom
mojombo authored
625
574637a @mojombo flesh out readme a little bit
mojombo authored
626 h2. License
d189e05 @mojombo first commit
mojombo authored
627
628 (The MIT License)
629
574637a @mojombo flesh out readme a little bit
mojombo authored
630 Copyright (c) 2008 Tom Preston-Werner
d189e05 @mojombo first commit
mojombo authored
631
632 Permission is hereby granted, free of charge, to any person obtaining
633 a copy of this software and associated documentation files (the
634 'Software'), to deal in the Software without restriction, including
635 without limitation the rights to use, copy, modify, merge, publish,
636 distribute, sublicense, and/or sell copies of the Software, and to
637 permit persons to whom the Software is furnished to do so, subject to
638 the following conditions:
639
640 The above copyright notice and this permission notice shall be
641 included in all copies or substantial portions of the Software.
642
643 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
644 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
645 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
646 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
647 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
648 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
649 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.