Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 172 lines (106 sloc) 8.645 kb
bffdeee @mojombo rename to Jekyll
mojombo authored
1 h1. Jekyll
d189e05 @mojombo first commit
mojombo authored
2
0c2feb9 @mojombo better readme
mojombo authored
3 Jekyll is a simple, blog aware, static site generator. It takes a template directory (representing the raw form of a website), runs it through Textile and Liquid converters, and spits out a complete, static website suitable for serving with Apache or your favorite web server. Visit "http://tom.preston-werner.com":http://tom.preston-werner.com to see an example of a Jekyll generated blog.
4
5 To understand how this all works, open up my "TPW":http://github.com/mojombo/tpw repo in a new browser window. I'll be referencing the code there.
6
7 Take a look at "index.html":http://github.com/mojombo/tpw/tree/master/index.html. This file represents the homepage of the site. At the top of the file is a chunk of YAML that contains metadata about the file. This data tells Jekyll what layout to give the file, what the page's title should be, etc. In this case, I specify that the "default" template should be used. You can find the layout files in the "_layouts":http://github.com/mojombo/tpw/tree/master/_layouts directory. If you open "default.html":http://github.com/mojombo/tpw/tree/master/_layouts/default.html you can see that the homepage is constructed by wrapping index.html with this layout.
8
9 You'll also notice Liquid templating code in these files. "Liquid":http://www.liquidmarkup.org/ is a simple, extensible templating language that makes it easy to embed data in your templates. For my homepage I wanted to have a list of all my blog posts. Jekyll hands me a Hash containing various data about my site. A reverse chronological list of all my blog posts can be found in <code>site.posts</code>. Each post, in turn, contains various fields such as <code>title</code> and <code>date</code>.
10
11 Jekyll gets the list of blog posts by parsing the files in the "_posts":http://github.com/mojombo/tpw/tree/master/_posts directory. Each post's filename contains the publishing date and slug (what shows up in the URL) that the final HTML file should have. Open up the file corresponding to a blog post: "2008-11-17-blogging-like-a-hacker.textile":http://github.com/mojombo/tpw/tree/master/_posts/2008-11-17-blogging-like-a-hacker.textile. GitHub renders textile files by default, so to better understand the file, click on the "raw":http://github.com/mojombo/tpw/tree/master/_posts/2008-11-17-blogging-like-a-hacker.textile?raw=true view to see the original file. Here I've specified the <code>post</code> layout. If you look at that file you'll see an example of a nested layout. Layouts can contain other layouts allowing you a great deal of flexibility in how pages are assembled. In my case I use a nested layout in order to show related posts for each blog entry. The YAML also specifies the post's title which is then embedded in the post's body via Liquid.
12
13 Posts are handled in a special way by Jekyll. The date you specify in the filename is used to construct the URL in the generated site. The example post, for instance, ends up at <code>http://tom.preston-werner.com/2008/11/17/blogging-like-a-hacker.html</code>.
14
15 Files that do not reside in directories prefixed with an underscore are mirrored into a corresponding directory structure in the generated site. If a file does not have a YAML preface, it is not run through the Liquid interpreter. Binary files are copied over unmodified.
16
17 In order to convert your raw site into the finished version, you simply run:
18
19 <pre class="terminal"><code>$ jekyll /path/to/raw/site /path/to/place/generated/site</code></pre>
20
21 Jekyll is still a very young project. I've only developed the exact functionality that I've needed. As time goes on I'd like to see the project mature and support additional features. If you end up using Jekyll for your own blog, drop me a line and let me know what you'd like to see in future versions. Better yet, fork the project over at GitHub and hack in the features yourself!
d189e05 @mojombo first commit
mojombo authored
22
574637a @mojombo flesh out readme a little bit
mojombo authored
23 h2. Example Proto-Site
d189e05 @mojombo first commit
mojombo authored
24
bffdeee @mojombo rename to Jekyll
mojombo authored
25 My own personal site/blog is generated with Jekyll.
d189e05 @mojombo first commit
mojombo authored
26
574637a @mojombo flesh out readme a little bit
mojombo authored
27 The proto-site repo ("http://github.com/mojombo/tpw":http://github.com/mojombo/tpw)
28 is converted into the actual site ("http://tom.preston-werner.com/":http://tom.preston-werner.com)
d189e05 @mojombo first commit
mojombo authored
29
b8ce181 @mojombo more info in the readme
mojombo authored
30 h2. Install
d189e05 @mojombo first commit
mojombo authored
31
b8ce181 @mojombo more info in the readme
mojombo authored
32 The best way to install Jekyll is via RubyGems:
33
34 $ sudo gem install jekyll
35
36 h2. Run
37
38 $ cd /path/to/proto/site
39 $ jekyll
40
d6a0227 @mojombo update readme with --lsi info
mojombo authored
41 This will generate the site and place it in /path/to/proto/site/_site.
42
43 There is an autobuild feature that will regenerate your site if any of the files change:
94bf6de @mojombo update readme
mojombo authored
44
45 $ jekyll --auto
46
d6a0227 @mojombo update readme with --lsi info
mojombo authored
47 By default, the "related posts" functionality will produce crappy results.
48 In order to get high quality results with a true LSI algorithm, you must
49 enable it (it may take some time to run if you have many posts):
50
51 $ jekyll --lsi
52
94bf6de @mojombo update readme
mojombo authored
53 If you'd like the generated site placed somewhere else:
b8ce181 @mojombo more info in the readme
mojombo authored
54
55 $ jekyll /path/to/place/generated/site
56
57 And if you don't want to be in the proto site root to run Jekyll:
58
59 $ jekyll /path/to/proto/site /path/to/place/generated/site
94bf6de @mojombo update readme
mojombo authored
60
c021cdd @JackDanger fixing typo in README
JackDanger authored
61 The autobuild feature can be used on any of the invocations.
b8ce181 @mojombo more info in the readme
mojombo authored
62
1e9040f @mojombo add code highlighting docs to readme
mojombo authored
63 h2. Filters, Tags, and Blocks
64
1d7b30b @mojombo document filters
mojombo authored
65 In addition to the built-in Liquid filters, tags, and blocks, Jekyll provides some additional items that you can use in your site.
66
67 h3. Date to XML Schema (Filter)
68
69 Convert a Time into XML Schema format.
70
71 {{ site.time | date_to_xmlschema }}
72
73 becomes
74
75 2008-11-17T13:07:54-08:00
76
77 h3. XML Escape (Filter)
78
79 Escape some text for use in XML.
80
81 {{ post.content | xml_escape }}
82
83 h3. Number of Words (Filter)
84
85 Count the number of words in some text.
86
87 {{ post.content | number_of_words }}
88
89 becomes
90
91 1337
92
93 h3. Include (Tag)
46169d3 @mojombo add include docs to readme
mojombo authored
94
95 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.
96
97 <pre>{% include sig.textile %}</pre>
98
99 Jekyll expects all include files to be placed in an <code>_includes</code> directory at the root of your source dir. So this will embed the contents of <code>/path/to/proto/site/_includes/sig.textile</code> into the calling file.
100
1d7b30b @mojombo document filters
mojombo authored
101 h3. Code Highlighting (Block)
1e9040f @mojombo add code highlighting docs to readme
mojombo authored
102
103 Jekyll has built in support for syntax highlighting of over "100
104 languages":http://pygments.org/languages/ via "Pygments":http://pygments.org/.
f57bb07 @mojombo remind about --pygments in readme
mojombo authored
105 In order to take advantage of this you'll need to have Pygments installed, and
106 the pygmentize binary must be in your path. When you run Jekyll, make sure you run it with Pygments support:
107
108 $ jekyll --pygments
1e9040f @mojombo add code highlighting docs to readme
mojombo authored
109
110 To denote a code block that should be highlighted:
111
112 <pre>
113 {% highlight ruby %}
114 def foo
115 puts 'foo'
116 end
117 {% endhighlight %}
118 </pre>
119
120 The argument to <code>highlight</code> is the language identifier. To find the
121 appropriate identifier to use for your favorite language, look for the "short
122 name" on the "Lexers":http://pygments.org/docs/lexers/ page.
123
124 In order for the highlighting to show up, you'll need to include a
125 highlighting stylesheet. For an example stylesheet you can look at
126 "syntax.css":http://github.com/mojombo/tpw/tree/master/css/syntax.css. These
127 are the same styles as used by GitHub and you are free to use them for your
128 own site.
129
b8ce181 @mojombo more info in the readme
mojombo authored
130 h2. Contribute
131
132 If you'd like to hack on Jekyll, grab the source from GitHub. To get
133 all of the dependencies, install the gem first.
d189e05 @mojombo first commit
mojombo authored
134
bffdeee @mojombo rename to Jekyll
mojombo authored
135 $ git clone git://github.com/mojombo/jekyll
b8ce181 @mojombo more info in the readme
mojombo authored
136
137 The best way to get your changes merged back into core is as follows:
138
31aa865 @mojombo proper list syntax
mojombo authored
139 # Fork mojombo/jekyll on GitHub
140 # Clone down your fork
141 # Create a topic branch to contain your change
142 # Hack away
94bf6de @mojombo update readme
mojombo authored
143 # Do not change the version number, I will do that on my end
31aa865 @mojombo proper list syntax
mojombo authored
144 # If necessary, rebase your commits into logical chunks, without errors
145 # Push the branch up to GitHub
94bf6de @mojombo update readme
mojombo authored
146 # Send me (mojombo) a pull request for your branch
d189e05 @mojombo first commit
mojombo authored
147
574637a @mojombo flesh out readme a little bit
mojombo authored
148 h2. License
d189e05 @mojombo first commit
mojombo authored
149
150 (The MIT License)
151
574637a @mojombo flesh out readme a little bit
mojombo authored
152 Copyright (c) 2008 Tom Preston-Werner
d189e05 @mojombo first commit
mojombo authored
153
154 Permission is hereby granted, free of charge, to any person obtaining
155 a copy of this software and associated documentation files (the
156 'Software'), to deal in the Software without restriction, including
157 without limitation the rights to use, copy, modify, merge, publish,
158 distribute, sublicense, and/or sell copies of the Software, and to
159 permit persons to whom the Software is furnished to do so, subject to
160 the following conditions:
161
162 The above copyright notice and this permission notice shall be
163 included in all copies or substantial portions of the Software.
164
165 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
166 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
167 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
168 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
169 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
170 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
171 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.