Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Jekyll is a blog-aware, static site generator in Ruby
Ruby Cucumber CSS HTML Other

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
lib
test
.gitignore
History.txt
Manifest.txt
README.textile
Rakefile
TODO
jekyll.gemspec

README.textile

Jekyll

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 or Markdown 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 to see an example of a Jekyll generated blog.

To understand how this all works, open up my TPW repo in a new browser window. I’ll be referencing the code there.

Take a look at 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 directory. If you open default.html you can see that the homepage is constructed by wrapping index.html with this layout.

You’ll also notice Liquid templating code in these files. Liquid 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 site.posts. Each post, in turn, contains various fields such as title and date.

Jekyll gets the list of blog posts by parsing the files in the _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. GitHub renders textile files by default, so to better understand the file, click on the raw view to see the original file. Here I’ve specified the post 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.

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 http://tom.preston-werner.com/2008/11/17/blogging-like-a-hacker.html.

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.

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!

Example Proto-Site

My own personal site/blog is generated with Jekyll.

The proto-site repo (http://github.com/mojombo/tpw)
is converted into the actual site (http://tom.preston-werner.com/)

Install

The best way to install Jekyll is via RubyGems:

$ sudo gem install mojombo-jekyll -s http://gems.github.com/

Run

$ cd /path/to/proto/site $ jekyll

This will generate the site and place it in /path/to/proto/site/_site. If you’d like the generated site placed somewhere else:

$ jekyll /path/to/place/generated/site

And if you don’t want to be in the proto site root to run Jekyll:

$ jekyll /path/to/proto/site /path/to/place/generated/site

Run Options

There is an autobuild feature that will regenerate your site if any of the files change. The autobuild feature can be used on any of the invocations:

$ jekyll —auto

By default, the “related posts” functionality will produce crappy results.
In order to get high quality results with a true LSI algorithm, you must
enable it (it may take some time to run if you have many posts):

$ jekyll —lsi

For static code highlighting, you can install Pygments (see below) and then use that to make your code blocks look pretty. To activate Pygments support during the conversion:

$ jekyll —pygments

Data

Jekyll traverses your site looking for files to process. Any files with YAML front matter (see below) are subject to processing. For each of these files, Jekyll makes a variety of data available to the pages via the Liquid templating system. The following is a reference of the available data.

Global

site Sitewide information. page For Posts, this is the union of the data in the YAML front matter and the computed data (such as URL and date). For regular pages, this is just the YAML front matter. content In layout files, this contains the content of the subview(s). In Posts or pages, this is undefined. related_posts If the page being processed is a Post, this contains a list of up to ten related Posts. For high quality results be sure to run the jekyll command with the —lsi option.

Site

site.time The current Time (when you run the jekyll command) site.posts A reverse chronological list of Posts

Post

post.title The title of the Post post.url The URL of the Post without the domain e.g. /2008/12/14/my-post.html post.date The Date assigned to the Post post.id An identifier unique to the Post (useful in RSS feeds) e.g. /2008/12/14/my-post post.content The content of the Post

YAML Front Matter

Any files that contain a YAML front matter block will be processed by Jekyll as special files. The front matter takes the form of:

- layout: post title: Blogging Like a Hacker -

Between the triple-dashed lines, you can set predefined variables (see below for a reference) or custom data of your own.

Predefined Global Variables

layout If set, this specifies the layout file to use. Use the layout name without file extension. Layout files must be placed in the _layouts directory.

Predefined Post Variables

permalink If you need your processed URLs to be something other than the default /year/month/day/title.html then you can set this variable and it will be used as the final URL.

Custom Variables

Any variables in the front matter that are not predefined are mixed into the
data that is sent to the Liquid templating engine during the conversion. For
instance, if you set a title, you can use that in your layout to
set the page title:

{{ page.title }}

Filters, Tags, and Blocks

In addition to the built-in Liquid filters, tags, and blocks, Jekyll provides some additional items that you can use in your site.

Date to XML Schema (Filter)

Convert a Time into XML Schema format.

{{ site.time | date_to_xmlschema }}

becomes

2008-11-17T13:07:54-08:00

XML Escape (Filter)

Escape some text for use in XML.

{{ post.content | xml_escape }}

Number of Words (Filter)

Count the number of words in some text.

{{ post.content | number_of_words }}

becomes

1337

Include (Tag)

If you have small page fragments that you wish to include in multiple places on your site, you can use the include tag.

{% include sig.textile %}

Jekyll expects all include files to be placed in an _includes directory at the root of your source dir. So this will embed the contents of /path/to/proto/site/_includes/sig.textile into the calling file.

Code Highlighting (Block)

Jekyll has built in support for syntax highlighting of over 100
languages
via Pygments.
In order to take advantage of this you’ll need to have Pygments installed, and
the pygmentize binary must be in your path. When you run Jekyll, make sure you run it with Pygments support:

$ jekyll —pygments

To denote a code block that should be highlighted:

{% highlight ruby %}
def foo
  puts 'foo'
end
{% endhighlight %}

The argument to highlight is the language identifier. To find the
appropriate identifier to use for your favorite language, look for the “short
name” on the Lexers page.

In order for the highlighting to show up, you’ll need to include a
highlighting stylesheet. For an example stylesheet you can look at
syntax.css. These
are the same styles as used by GitHub and you are free to use them for your
own site.

Contribute

If you’d like to hack on Jekyll, grab the source from GitHub. To get
all of the dependencies, install the gem first.

$ git clone git://github.com/mojombo/jekyll

The best way to get your changes merged back into core is as follows:

  1. Fork mojombo/jekyll on GitHub
  2. Clone down your fork
  3. Create a topic branch to contain your change
  4. Hack away
  5. Do not change the version number, I will do that on my end
  6. If necessary, rebase your commits into logical chunks, without errors
  7. Push the branch up to GitHub
  8. Send me (mojombo) a pull request for your branch

License

(The MIT License)

Copyright © 2008 Tom Preston-Werner

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
‘Software’), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Something went wrong with that request. Please try again.