Veerasundaravel's Ruby on Rails Weblog

October 4, 2010

Jekyll – Ruby gem for static site generation

Filed under: Gems — Tags: , , , , — Veerasundaravel @ 12:09 pm

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. This is also the engine behind GitHub Pages, which you can use to host your project’s page or blog right here from GitHub.

Usage

Creating a Jekyll site usually involves the following, once jekyll is installed.

  1. Set up the basic structure of the site
  2. Create some posts, or import them from your previous platform
  3. Run your site locally to see how it looks
  4. Deploy your site

Basic Structure

Jekyll at its core is a text transformation engine. The concept behind the system is this: you give it text written in your favorite markup language, be that Markdown, Textile, or just plain HTML, and it churns that through a layout or series of layout files. Throughout that process you can tweak how you want the site URLs to look, what data gets displayed on the layout and more. This is all done through strictly editing files, and the web interface is the final product.

A basic Jekyll site usually looks something like this:

.
|-- _config.yml
|-- _layouts
|   |-- default.html
|   `-- post.html
|-- _posts
|   |-- 2007-10-29-why-every-programmer-should-play-nethack.textile
|   `-- 2009-04-26-barcamp-boston-4-roundup.textile
|-- _site
`-- index.html

An overview of what each of these does:

_config.yml

Stores configuration data. A majority of these options can be specified from the command line exectuable but it’s easier to throw them in here so you don’t have to remember them.

_layouts

These are the templates which posts are inserted into. Layouts are defined on a post-by-post basis in the YAML front matter, which is described in the next section. The liquid tag {{ content }} is used to inject data onto the page.

_posts

Your dynamic content, so to speak. The format of these files is important, as named as YEAR-MONTH-DATE-title.MARKUP. The Permalinks can be adjusted very flexibly for each post, but the date and markup language are determined solely by the file name.

_site

This is where the generated site will be placed once Jekyll is done transforming it. It’s probably a good idea to add this to your .gitignore file.

index.html

Granted that this file has a YAML Front Matter section, it will be transformed by Jekyll. The same will happen for any .html, .markdown, or .textile file in your site’s root directory.

Other Files/Folders

Every other directory and file except for those listed above will be transferred over as expected. For example, you could have a css folder, a favicon.ico, etc, etc. There’s plenty of sites already using Jekyll if you’re curious as to how they’re laid out.

Any files in these directories will be parsed and transformed, according to the same rules mentioned previously for files in the root directory.

Running Jekyll

Usually this is done through the jekyll executable, which is installed with the gem. In order to get a server up and running with your Jekyll site, run:

jekyll --server

and then browse to http://0.0.0.0:4000. There’s plenty of configuration options available to you as well.

On Ubuntu, you may need to add /var/lib/gems/1.8/bin/ to your path.

Deployment

Since Jekyll simply generates a folder filled with HTML files, it can be served using practically any available web server out there.

Advertisements

5 Comments »

  1. hello!This was a really marvelous blog!
    I come from roma, I was luck to discover your Topics in yahoo
    Also I get much in your subject really thank your very much i will come later

    Comment by bet365 italia — October 6, 2010 @ 11:14 am

  2. Jekyll – Ruby gem for static site generation « Veerasundaravel’s Weblog
    Cool stuff

    Pingback by Livinglies’s Weblog | WebLogic Daily News — October 6, 2010 @ 11:42 pm

  3. thanks

    Comment by Hermit — October 13, 2010 @ 3:35 pm

  4. Hey there would you mind letting me know which web host you’re working with? I’ve loaded your blog in 3
    different internet browsers and I must say this blog loads a lot faster then most.
    Can you suggest a good hosting provider at a
    honest price? Many thanks, I appreciate it!

    Comment by Ullas Soman — February 21, 2013 @ 8:14 pm

  5. Have you ever considered about including a little bit more than just your articles?
    I mean, what you say is important and everything. However just imagine if you
    added some great photos or videos to give your posts more, “pop”!
    Your content is excellent but with images and video clips, this website could undeniably
    be one of the very best in its niche. Good blog!

    Comment by Mellissa — May 3, 2013 @ 7:23 am


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: