metajack / jekyll forked from mojombo/jekyll

Jekyll is a blog-aware, static site generator in Ruby

This URL has Read+Write access

jekyll / README.textile
raw normal view history
bffdeee6 » mojombo 2008-11-17 rename to Jekyll 1 h1. Jekyll
d189e05d » mojombo 2008-10-19 first commit 2
3a21a0b2 » mojombo 2008-12-14 break long lines in readme 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!
d189e05d » mojombo 2008-10-19 first commit 66
574637ab » mojombo 2008-11-05 flesh out readme a little bit 67 h2. Example Proto-Site
d189e05d » mojombo 2008-10-19 first commit 68
bffdeee6 » mojombo 2008-11-17 rename to Jekyll 69 My own personal site/blog is generated with Jekyll.
d189e05d » mojombo 2008-10-19 first commit 70
3a21a0b2 » mojombo 2008-12-14 break long lines in readme 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)
d189e05d » mojombo 2008-10-19 first commit 75
b8ce1810 » mojombo 2008-11-22 more info in the readme 76 h2. Install
d189e05d » mojombo 2008-10-19 first commit 77
b8ce1810 » mojombo 2008-11-22 more info in the readme 78 The best way to install Jekyll is via RubyGems:
79
528a18f7 » mojombo 2008-12-14 reorganize readme 80 $ sudo gem install mojombo-jekyll -s http://gems.github.com/
b8ce1810 » mojombo 2008-11-22 more info in the readme 81
0e81edd0 » Mark Reid 2008-12-14 Added note about dependencies. 82 Jekyll requires the gems `directory_watcher`, `liquid`, `open4`,
59080271 » mojombo 2008-12-15 allow use of rdiscount if -... 83 and `maruku` (for markdown support). These are automatically
b094b933 » Mark Reid 2008-12-14 Replaced rdiscount with Mar... 84 installed by the gem install command.
85
86 Maruku comes with optional support for LaTeX to PNG rendering via
87 "blahtex":http://gva.noekeon.org/blahtexml/ (Version 0.6) which must be in
88 your $PATH along with `dvips`.
89
90 (NOTE: the version of maruku I am using is `remi-maruku` on GitHub as it
91 does not assume a fixed location for `dvips`.)
0e81edd0 » Mark Reid 2008-12-14 Added note about dependencies. 92
b8ce1810 » mojombo 2008-11-22 more info in the readme 93 h2. Run
94
95 $ cd /path/to/proto/site
96 $ jekyll
97
3a21a0b2 » mojombo 2008-12-14 break long lines in readme 98 This will generate the site and place it in /path/to/proto/site/_site. If
99 you'd like the generated site placed somewhere else:
528a18f7 » mojombo 2008-12-14 reorganize readme 100
101 $ jekyll /path/to/place/generated/site
102
103 And if you don't want to be in the proto site root to run Jekyll:
104
105 $ jekyll /path/to/proto/site /path/to/place/generated/site
106
107 h2. Run Options
d6a02278 » mojombo 2008-12-12 update readme with --lsi info 108
3a21a0b2 » mojombo 2008-12-14 break long lines in readme 109 There is an autobuild feature that will regenerate your site if any of the
110 files change. The autobuild feature can be used on any of the invocations:
94bf6de8 » mojombo 2008-12-06 update readme 111
112 $ jekyll --auto
113
d6a02278 » mojombo 2008-12-12 update readme with --lsi info 114 By default, the "related posts" functionality will produce crappy results.
115 In order to get high quality results with a true LSI algorithm, you must
116 enable it (it may take some time to run if you have many posts):
117
118 $ jekyll --lsi
119
3a21a0b2 » mojombo 2008-12-14 break long lines in readme 120 For static code highlighting, you can install Pygments (see below) and then
121 use that to make your code blocks look pretty. To activate Pygments support
122 during the conversion:
b8ce1810 » mojombo 2008-11-22 more info in the readme 123
528a18f7 » mojombo 2008-12-14 reorganize readme 124 $ jekyll --pygments
b8ce1810 » mojombo 2008-11-22 more info in the readme 125
59080271 » mojombo 2008-12-15 allow use of rdiscount if -... 126 By default, Jekyll uses "Maruku":http://maruku.rubyforge.org (pure Ruby) for
127 Markdown support. If you'd like to use RDiscount (faster, but requires
128 compilation), you must install it (gem install rdiscount) and then you can
129 have it used instead:
130
131 $ jekyll --rdiscount
132
6b582ffc » mojombo 2008-12-14 document liquid data 133 h2. Data
134
3a21a0b2 » mojombo 2008-12-14 break long lines in readme 135 Jekyll traverses your site looking for files to process. Any files with YAML
136 front matter (see below) are subject to processing. For each of these files,
137 Jekyll makes a variety of data available to the pages via the Liquid
138 templating system. The following is a reference of the available data.
0c270cb1 » mojombo 2008-12-14 better data docs 139
140 h3. Global
141
142 site
143 Sitewide information.
144
145 page
146 For Posts, this is the union of the data in the YAML front matter and the
147 computed data (such as URL and date). For regular pages, this is just the
148 YAML front matter.
149
150 content
151 In layout files, this contains the content of the subview(s). In Posts or
152 pages, this is undefined.
153
6b582ffc » mojombo 2008-12-14 document liquid data 154 h3. Site
155
156 site.time
043fb15c » mojombo 2008-12-14 readme clarifications 157 The current Time (when you run the jekyll command).
6b582ffc » mojombo 2008-12-14 document liquid data 158
159 site.posts
043fb15c » mojombo 2008-12-14 readme clarifications 160 A reverse chronological list of all Posts.
6b582ffc » mojombo 2008-12-14 document liquid data 161
d48157cf » mojombo 2008-12-14 move related_posts into sit... 162 site.related_posts
163 If the page being processed is a Post, this contains a list of up to ten
043fb15c » mojombo 2008-12-14 readme clarifications 164 related Posts. By default, these are low quality but fast to compute. For
165 high quality but slow to compute results, run the jekyll command with the
166 --lsi (latent semantic indexing) option.
d48157cf » mojombo 2008-12-14 move related_posts into sit... 167
6b582ffc » mojombo 2008-12-14 document liquid data 168 h3. Post
169
170 post.title
043fb15c » mojombo 2008-12-14 readme clarifications 171 The title of the Post.
6b582ffc » mojombo 2008-12-14 document liquid data 172
173 post.url
043fb15c » mojombo 2008-12-14 readme clarifications 174 The URL of the Post without the domain.
0d18c6b1 » mojombo 2008-12-14 readme data tweaks 175 e.g. /2008/12/14/my-post.html
6b582ffc » mojombo 2008-12-14 document liquid data 176
177 post.date
043fb15c » mojombo 2008-12-14 readme clarifications 178 The Date assigned to the Post.
6b582ffc » mojombo 2008-12-14 document liquid data 179
180 post.id
043fb15c » mojombo 2008-12-14 readme clarifications 181 An identifier unique to the Post (useful in RSS feeds).
0d18c6b1 » mojombo 2008-12-14 readme data tweaks 182 e.g. /2008/12/14/my-post
6b582ffc » mojombo 2008-12-14 document liquid data 183
184 post.content
043fb15c » mojombo 2008-12-14 readme clarifications 185 The content of the Post.
6b582ffc » mojombo 2008-12-14 document liquid data 186
5c46fd62 » mojombo 2008-12-14 document yaml front matter 187 h2. YAML Front Matter
188
3a21a0b2 » mojombo 2008-12-14 break long lines in readme 189 Any files that contain a YAML front matter block will be processed by Jekyll
190 as special files. The front matter must be the first thing in the file and
191 takes the form of:
5c46fd62 » mojombo 2008-12-14 document yaml front matter 192
8bea61eb » mojombo 2008-12-14 fix formatting 193 <pre>
7716e64e » mojombo 2008-12-14 fix formatting again 194 ---
195 layout: post
196 title: Blogging Like a Hacker
197 ---
8bea61eb » mojombo 2008-12-14 fix formatting 198 </pre>
5c46fd62 » mojombo 2008-12-14 document yaml front matter 199
3a21a0b2 » mojombo 2008-12-14 break long lines in readme 200 Between the triple-dashed lines, you can set predefined variables (see below
201 for a reference) or custom data of your own.
5c46fd62 » mojombo 2008-12-14 document yaml front matter 202
203 h3. Predefined Global Variables
204
516afee8 » mojombo 2008-12-14 fix formatting one more time 205 layout
206 If set, this specifies the layout file to use. Use the layout file
207 name without file extension. Layout files must be placed in the
208 <code>_layouts</code> directory.
5c46fd62 » mojombo 2008-12-14 document yaml front matter 209
210 h3. Predefined Post Variables
211
212 permalink
213 If you need your processed URLs to be something other than the default
214 /year/month/day/title.html then you can set this variable and it will
215 be used as the final URL.
216
217 h3. Custom Variables
218
219 Any variables in the front matter that are not predefined are mixed into the
220 data that is sent to the Liquid templating engine during the conversion. For
221 instance, if you set a <code>title</code>, you can use that in your layout to
222 set the page title:
223
7716e64e » mojombo 2008-12-14 fix formatting again 224 <pre>
225 <title>{{ page.title }}</title>
226 </pre>
5c46fd62 » mojombo 2008-12-14 document yaml front matter 227
1e9040f3 » mojombo 2008-12-13 add code highlighting docs ... 228 h2. Filters, Tags, and Blocks
229
3a21a0b2 » mojombo 2008-12-14 break long lines in readme 230 In addition to the built-in Liquid filters, tags, and blocks, Jekyll provides
231 some additional items that you can use in your site.
1d7b30b7 » mojombo 2008-12-14 document filters 232
233 h3. Date to XML Schema (Filter)
234
235 Convert a Time into XML Schema format.
236
237 {{ site.time | date_to_xmlschema }}
238
239 becomes
240
241 2008-11-17T13:07:54-08:00
242
243 h3. XML Escape (Filter)
244
245 Escape some text for use in XML.
246
247 {{ post.content | xml_escape }}
248
249 h3. Number of Words (Filter)
250
251 Count the number of words in some text.
252
253 {{ post.content | number_of_words }}
254
255 becomes
256
257 1337
258
259 h3. Include (Tag)
46169d3f » mojombo 2008-12-13 add include docs to readme 260
261 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.
262
263 <pre>{% include sig.textile %}</pre>
264
3a21a0b2 » mojombo 2008-12-14 break long lines in readme 265 Jekyll expects all include files to be placed in an <code>_includes</code>
266 directory at the root of your source dir. So this will embed the contents of
267 <code>/path/to/proto/site/_includes/sig.textile</code> into the calling file.
46169d3f » mojombo 2008-12-13 add include docs to readme 268
1d7b30b7 » mojombo 2008-12-14 document filters 269 h3. Code Highlighting (Block)
1e9040f3 » mojombo 2008-12-13 add code highlighting docs ... 270
271 Jekyll has built in support for syntax highlighting of over "100
272 languages":http://pygments.org/languages/ via "Pygments":http://pygments.org/.
f57bb072 » mojombo 2008-12-13 remind about --pygments in ... 273 In order to take advantage of this you'll need to have Pygments installed, and
3a21a0b2 » mojombo 2008-12-14 break long lines in readme 274 the pygmentize binary must be in your path. When you run Jekyll, make sure you
275 run it with Pygments support:
f57bb072 » mojombo 2008-12-13 remind about --pygments in ... 276
277 $ jekyll --pygments
1e9040f3 » mojombo 2008-12-13 add code highlighting docs ... 278
279 To denote a code block that should be highlighted:
280
281 <pre>
282 {% highlight ruby %}
283 def foo
284 puts 'foo'
285 end
286 {% endhighlight %}
287 </pre>
288
289 The argument to <code>highlight</code> is the language identifier. To find the
290 appropriate identifier to use for your favorite language, look for the "short
291 name" on the "Lexers":http://pygments.org/docs/lexers/ page.
292
293 In order for the highlighting to show up, you'll need to include a
294 highlighting stylesheet. For an example stylesheet you can look at
295 "syntax.css":http://github.com/mojombo/tpw/tree/master/css/syntax.css. These
296 are the same styles as used by GitHub and you are free to use them for your
297 own site.
298
b8ce1810 » mojombo 2008-11-22 more info in the readme 299 h2. Contribute
300
301 If you'd like to hack on Jekyll, grab the source from GitHub. To get
302 all of the dependencies, install the gem first.
d189e05d » mojombo 2008-10-19 first commit 303
bffdeee6 » mojombo 2008-11-17 rename to Jekyll 304 $ git clone git://github.com/mojombo/jekyll
b8ce1810 » mojombo 2008-11-22 more info in the readme 305
306 The best way to get your changes merged back into core is as follows:
307
31aa865d » mojombo 2008-11-22 proper list syntax 308 # Fork mojombo/jekyll on GitHub
309 # Clone down your fork
310 # Create a topic branch to contain your change
311 # Hack away
94bf6de8 » mojombo 2008-12-06 update readme 312 # Do not change the version number, I will do that on my end
31aa865d » mojombo 2008-11-22 proper list syntax 313 # If necessary, rebase your commits into logical chunks, without errors
314 # Push the branch up to GitHub
94bf6de8 » mojombo 2008-12-06 update readme 315 # Send me (mojombo) a pull request for your branch
d189e05d » mojombo 2008-10-19 first commit 316
574637ab » mojombo 2008-11-05 flesh out readme a little bit 317 h2. License
d189e05d » mojombo 2008-10-19 first commit 318
319 (The MIT License)
320
574637ab » mojombo 2008-11-05 flesh out readme a little bit 321 Copyright (c) 2008 Tom Preston-Werner
d189e05d » mojombo 2008-10-19 first commit 322
323 Permission is hereby granted, free of charge, to any person obtaining
324 a copy of this software and associated documentation files (the
325 'Software'), to deal in the Software without restriction, including
326 without limitation the rights to use, copy, modify, merge, publish,
327 distribute, sublicense, and/or sell copies of the Software, and to
328 permit persons to whom the Software is furnished to do so, subject to
329 the following conditions:
330
331 The above copyright notice and this permission notice shall be
332 included in all copies or substantial portions of the Software.
333
334 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
335 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
336 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
337 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
338 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
339 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
340 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.