Static Site Blogging with Jekyll - OS X Development

Lately, I've been doing all development on my Macbook. I'm on OS X 10.5.8 Leopard and I had been looking for a blogging solution that doesn't involve a database or scripting, just static pages. I came across jekyll. "Jekyll is a blog-aware, static site generator in Ruby." In simpler terms, jekyll is a command line tool for generating a blog site without scripting or databases.

OS X 10.5.8 Leopard comes with ruby and ruby gems but somewhere in the mix, the repository site for ruby changed and trying to install anything with RubyGems will error out.

Grab a fresh version on RubyGems.

Extract, then run:

ruby setup.rb

Almost ready to install jekyll; try this command:

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

You might have gotten a error like this:

Failed to build gem native extension.

/usr/bin/ruby extconf.rb
can't find header files for ruby.

Or maybe it worked perfectly. If you did get this error, you need Xcode. Grab it from apple's developer site. After installing that you should be ready to build your jekyll blog.

Now, jekyll does have a built in web server, but I've got all my sites served by a local Apache server for development purposes. To turn on Apache, go to System Prefernces -> Sharing -> Web Sharing checkbox. The default location Apache serves files from is /Library/Webserver/Documents/.

Assuming you're going to use the root directory of your webserver (http://localhost/), here's the directory structure we'll need for jekyll.

/Library/Webserver/Documents/_layouts
/Library/Webserver/Documents/_posts
/Library/Webserver/Documents/_site

_layouts is where you will definte the structure of your pages using YAML Front Matter. For my site, I use a layout for my front page and a layout for a blog post bage. Thus, my layout folder contains two files: blog.html and default.html.

Here is default.html.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="description" content="Portfolio and work profile from Matthew Hurst, web designer and developer." />
<meta name="keywords" content="web design, web development, online portfolio, previous works, matthew hurst, matthew j hurst, hurst, matthew" />
<title>{{ page.title }}</title>
<link href="style_{{ page.style }}.css" rel="stylesheet" type="text/css" />
</head>

<body>

<div id="container">
{{ content }}
</div>
</body>
</html>

As you can see, it looks like a plain html file with the exception of {{ variable }}. These are tags jekyll will use to generate static pages from your templates and content. This particular template is only used on my front page. You can use these tags in your jekyll content pages as well. For example, here's a section from my index.html which lists my most recent posts in the top right corner of the page.

<strong>RECENT POSTS</strong><br />
{% for post in site.posts limit:5 %}
<a href="{{ post.url }}">{{ post.title_short }}</a> >>> <em>Posted on {{ post.date | date_to_long_string }}.</em><br />
{% endfor %}
<a href="all_posts.html"><span class="grey">...SEE ALL</span></a>

Jekyll will parse pretty much every HTML file in your working directory. It's also important to note that all content pages must include a header formatting like this:

---
layout: default
title: Matthew Hurst - Design and Development
style: orange
---

The layout variable is the only really necessary piece. You can pretty much make up as many other variables as you see fit. Here I use a title and a style. So I wrote a template for my main page, some content; and a template for my blog posts. Now we're going to move on and make an actual post.

Blog posts are simply content pages in the _posts/ directory. They must be named in the following format: yyyy-mm-dd-title-of-your-post. Here is an example blog post, 2009-11-24-example-post.html:

---
layout: blog
title: A Sample Blog Post
---

This is a sample blog post!

After you build some layouts, content, and blog posts it's time to build your pages. Open a terminal and run jekyll from your working directory. Jekyll will create an _site/ directory with your generated content. By default, jekyll will generate a folder structure based on the date and time of your posts(i.e. http://yoursite.com/2009/11/22/jekyll-blogging/). To change this, run jekyll with the --permalink parameter. Here is some more in-depth information on adjusting your permalinks. For my site, I'm taking out the date-based directories using:

jekyll --permalink=/blog/:title

Static Site Blogging with Jekyll - OS X Development

24 November 2009