cypher-jekyll 0.5.2 → 0.5.3
Sign up to get free protection for your applications and to get access to all the features.
- data/.gitignore +6 -0
- data/History.txt +0 -12
- data/README.textile +630 -22
- data/Rakefile +2 -2
- data/TODO +3 -0
- data/VERSION.yml +1 -1
- data/features/create_sites.feature +46 -0
- data/features/embed_filters.feature +60 -0
- data/features/permalinks.feature +54 -0
- data/features/post_data.feature +155 -0
- data/features/site_configuration.feature +40 -0
- data/features/site_data.feature +51 -0
- data/features/step_definitions/jekyll_steps.rb +118 -0
- data/features/support/env.rb +18 -0
- data/jekyll.gemspec +120 -0
- data/lib/jekyll/filters.rb +1 -5
- data/lib/jekyll/post.rb +2 -3
- data/lib/jekyll/site.rb +9 -6
- data/test/helper.rb +0 -3
- data/test/test_filters.rb +0 -8
- data/test/test_post.rb +0 -7
- data/test/test_site.rb +0 -8
- data/test/test_tags.rb +7 -72
- metadata +18 -7
- data/test/source/_posts/2009-03-12-hash-#1.markdown +0 -6
data/History.txt
CHANGED
@@ -1,15 +1,3 @@
|
|
1
|
-
== 0.5.1
|
2
|
-
* Major Enhancements
|
3
|
-
* Next/previous posts in site payload [github.com/pantulis, github.com/tomo]
|
4
|
-
* Permalink templating system
|
5
|
-
* Moved most of the README out to the GitHub wiki
|
6
|
-
* Exclude option in configuration so specified files won't be brought over with generated site [github.com/duritong]
|
7
|
-
* Bug Fixes
|
8
|
-
* Making sure config.yaml references are all gone, using only config.yml
|
9
|
-
* Fixed syntax highlighting breaking for UTF-8 code [github.com/henrik]
|
10
|
-
* Worked around RDiscount bug that prevents Markdown from getting parsed after highlight [github.com/henrik]
|
11
|
-
* CGI escaped post titles [github.com/Chrononaut]
|
12
|
-
|
13
1
|
== 0.5.0 / 2009-04-07
|
14
2
|
* Minor Enhancements
|
15
3
|
* Ability to set post categories via YAML [github.com/qrush]
|
data/README.textile
CHANGED
@@ -2,31 +2,626 @@ h1. Jekyll
|
|
2
2
|
|
3
3
|
By Tom Preston-Werner, Nick Quaranto, and many awesome contributors!
|
4
4
|
|
5
|
-
|
5
|
+
h2. Description
|
6
6
|
|
7
|
-
|
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.
|
8
13
|
|
9
|
-
|
10
|
-
|
11
|
-
|
12
|
-
* Fork and "Contribute":http://wiki.github.com/mojombo/jekyll/contribute your own modifications
|
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.
|
13
17
|
|
14
|
-
|
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.
|
15
29
|
|
16
|
-
|
17
|
-
|
18
|
-
|
19
|
-
|
20
|
-
|
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>.
|
21
37
|
|
22
|
-
|
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.
|
41
|
+
Each post's filename contains (by default) the publishing date and slug (what shows up in the
|
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.
|
23
54
|
|
24
|
-
|
25
|
-
|
26
|
-
|
27
|
-
|
28
|
-
|
29
|
-
|
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
|
+
|
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
|
+
|
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.
|
71
|
+
|
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!
|
83
|
+
|
84
|
+
h2. Example Proto-Site
|
85
|
+
|
86
|
+
My own personal site/blog is generated with Jekyll.
|
87
|
+
|
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)
|
92
|
+
|
93
|
+
h2. Install
|
94
|
+
|
95
|
+
The best way to install Jekyll is via RubyGems:
|
96
|
+
|
97
|
+
$ sudo gem install mojombo-jekyll -s http://gems.github.com/
|
98
|
+
|
99
|
+
Jekyll requires the gems `directory_watcher`, `liquid`, `open4`,
|
100
|
+
and `maruku` (for markdown support). These are automatically
|
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`.)
|
109
|
+
|
110
|
+
h2. Run
|
111
|
+
|
112
|
+
$ cd /path/to/proto/site
|
113
|
+
$ jekyll
|
114
|
+
|
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:
|
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
|
125
|
+
|
126
|
+
h3. Autobuild
|
127
|
+
|
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:
|
130
|
+
|
131
|
+
$ jekyll --auto
|
132
|
+
|
133
|
+
h3. Related Posts
|
134
|
+
|
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
|
+
|
141
|
+
h3. Code Highlighting
|
142
|
+
|
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:
|
146
|
+
|
147
|
+
$ jekyll --pygments
|
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]
|
154
|
+
|
155
|
+
h3. Markdown Processor
|
156
|
+
|
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
|
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
|
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
|
+
|
179
|
+
Note that pages and posts must have a YAML metadata block at the top to be
|
180
|
+
converted. Layouts don't need to.
|
181
|
+
|
182
|
+
Haml content is intentionally not filtered, so you can use any Ruby code.
|
183
|
+
|
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
|
+
|
196
|
+
h3. Local Server
|
197
|
+
|
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
|
201
|
+
can launch a simple WEBrick server (works well in conjunction with --auto).
|
202
|
+
Default port is 4000:
|
203
|
+
|
204
|
+
$ jekyll --server [PORT]
|
205
|
+
|
206
|
+
h3. Permalink Style
|
207
|
+
|
208
|
+
By default, the permalink for each post begins with its date in 'YYYY/MM/DD'
|
209
|
+
format.
|
210
|
+
|
211
|
+
If you do not wish to have the date appear in the URL of each post,
|
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
|
+
|
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]
|
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.
|
233
|
+
|
234
|
+
h2. Configuration File
|
235
|
+
|
236
|
+
All of the options listed above can be specified on a site-by-site basis in
|
237
|
+
a '_config.yml' file at the root of the site's source. As the filename
|
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
|
+
|
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
|
+
|
280
|
+
h2. Data
|
281
|
+
|
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,
|
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.
|
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
|
299
|
+
Pages, this is undefined.
|
300
|
+
|
301
|
+
h3. Site
|
302
|
+
|
303
|
+
site.time
|
304
|
+
The current Time (when you run the jekyll command).
|
305
|
+
|
306
|
+
site.posts
|
307
|
+
A reverse chronological list of all Posts.
|
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)
|
323
|
+
|
324
|
+
site.related_posts
|
325
|
+
If the page being processed is a Post, this contains a list of up to ten
|
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.
|
329
|
+
|
330
|
+
site.categories.CATEGORY
|
331
|
+
The list of all Posts in category CATEGORY.
|
332
|
+
|
333
|
+
site.tags.TAG
|
334
|
+
The list of all Posts tagged TAG.
|
335
|
+
|
336
|
+
h3. Post
|
337
|
+
|
338
|
+
post.title
|
339
|
+
The title of the Post.
|
340
|
+
|
341
|
+
post.url
|
342
|
+
The URL of the Post without the domain.
|
343
|
+
e.g. /2008/12/14/my-post.html
|
344
|
+
|
345
|
+
post.date
|
346
|
+
The Date (actually a Time object) assigned to the Post.
|
347
|
+
|
348
|
+
post.id
|
349
|
+
An identifier unique to the Post (useful in RSS feeds).
|
350
|
+
e.g. /2008/12/14/my-post
|
351
|
+
|
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
|
+
|
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
|
+
|
368
|
+
post.content
|
369
|
+
The content of the Post.
|
370
|
+
|
371
|
+
h2. YAML Front Matter
|
372
|
+
|
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:
|
376
|
+
|
377
|
+
<pre>
|
378
|
+
---
|
379
|
+
layout: post
|
380
|
+
title: Blogging Like a Hacker
|
381
|
+
---
|
382
|
+
</pre>
|
383
|
+
|
384
|
+
Between the triple-dashed lines, you can set predefined variables (see below
|
385
|
+
for a reference) or custom data of your own.
|
386
|
+
|
387
|
+
h3. Predefined Global Variables
|
388
|
+
|
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.
|
393
|
+
|
394
|
+
A default layout for posts can be set in the configuration file.
|
395
|
+
See above.
|
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
|
+
|
404
|
+
published
|
405
|
+
Set to false if you don't want a post to show up when the site is
|
406
|
+
generated.
|
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"
|
413
|
+
|
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.
|
418
|
+
|
419
|
+
tags
|
420
|
+
Similar to categories and topics but not reflected in the URL.
|
421
|
+
|
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
|
+
|
429
|
+
<pre>
|
430
|
+
<title>{{ page.title }}</title>
|
431
|
+
</pre>
|
432
|
+
|
433
|
+
h2. Filters, Tags, and Blocks
|
434
|
+
|
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.
|
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
|
+
|
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
|
473
|
+
|
474
|
+
h3. Textilize
|
475
|
+
|
476
|
+
Convert a Textile-formatted string into HTML, formatted via RedCloth
|
477
|
+
|
478
|
+
{{ page.excerpt | textilize }}
|
479
|
+
|
480
|
+
h3. Include (Tag)
|
481
|
+
|
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.
|
484
|
+
|
485
|
+
<pre>{% include sig.textile %}</pre>
|
486
|
+
|
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.
|
490
|
+
|
491
|
+
h3. Code Highlighting (Block)
|
492
|
+
|
493
|
+
Jekyll has built in support for syntax highlighting of over "100
|
494
|
+
languages":http://pygments.org/languages/ via "Pygments":http://pygments.org/.
|
495
|
+
In order to take advantage of this you'll need to have Pygments installed, and
|
496
|
+
the pygmentize binary must be in your path. When you run Jekyll, make sure you
|
497
|
+
run it with Pygments support:
|
498
|
+
|
499
|
+
$ jekyll --pygments
|
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
|
+
|
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:
|
520
|
+
|
521
|
+
<pre>
|
522
|
+
{% highlight ruby linenos %}
|
523
|
+
def foo
|
524
|
+
puts 'foo'
|
525
|
+
end
|
526
|
+
{% endhighlight %}
|
527
|
+
</pre>
|
528
|
+
|
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
|
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.
|
536
|
+
|
537
|
+
h2. Categories
|
538
|
+
|
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:
|
542
|
+
|
543
|
+
<pre>
|
544
|
+
{% for post in site.categories.foo %}
|
545
|
+
<li><span>{{ post.date | date_to_string }}</span> - {{ post.title }}</li>
|
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
|
+
|
553
|
+
h2. Tags
|
554
|
+
|
555
|
+
Tags are like categories or topics but not reflected in the URL.
|
556
|
+
|
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
|
+
|
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
|
+
|
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
|
+
|
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
|
624
|
+
# Create an issue on mojombo/grit with a description and link to your branch
|
30
625
|
|
31
626
|
h2. License
|
32
627
|
|
@@ -34,8 +629,21 @@ h2. License
|
|
34
629
|
|
35
630
|
Copyright (c) 2008 Tom Preston-Werner
|
36
631
|
|
37
|
-
Permission is hereby granted, free of charge, to any person obtaining
|
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:
|
38
639
|
|
39
|
-
The above copyright notice and this permission notice shall be
|
640
|
+
The above copyright notice and this permission notice shall be
|
641
|
+
included in all copies or substantial portions of the Software.
|
40
642
|
|
41
|
-
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
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.
|