Why Jekyll?
As a Rubyist you’ll often see example code that starts like rails new blog and it is tempting. Many of us have gone down that rabbit hole because, as a programmer, it feels right to start from scratch and have control of every little aspect. It’s your baby, and you want it to be perfect.
That isn’t important!
With few exceptions, writing your own web application for a blog is not only overkill but actually reduces your ability to produce content. In the end, you are creating a blog because you believe you have something to say, so say it. That’s what Jekyll does: it stays out of your way, giving you all the convenience of a custom application without having to waste all of your time in development.
I recently made the switch from Rails to Jekyll on my own blog. It’s been a rewarding experience and I think it might be right for you. First, let’s talk about what Jekyll is.
Jekyll is a blog-aware static website generator.
Essentially, it’s an engine that chews up your markdown and spits out a bunch of HTML pages in a _site directory so that you can serve it from your favorite webserver (Nginx/Apache). There is actually a lot more to it, but once you have the basic structure down, all you have to do is write the content and it will output a pretty website.
It uses Liquid[1] templating to allow more semantic organization within your site, as well as extensible helper methods. It also supports several markdown converters, so you can write in whatever flavor you prefer (i.e. Markdown, Textile, HTML, et al.)
Now that you are somewhat acquainted with Jekyll, we can dive straight into creating a blog.
Basics
The structure of a Jekyll site is somewhat flexible with a few required elements. There are a number of great sites listed on the Jekyll wiki[2] that offer some insight into what constitutes a Jekyll site. That said, we’ll be using @mojombo’s site as a reference, with a few modifications.
If you are going to follow along, run this:
[gist id=”2296836″]
Once you’ve done that you should have a tree that looks like the following (minus the posts).
[gist id=”2296842″]
This tree has all you need to get started producing content. Once you have your first post ready (clever name right?), you simply type:
[gist id=’2296844′]
Then navigate to http://localhost:4000/2012/03/27/your-first-post-in-markdown.html and you’ll see your text magically displayed in HTML. Before this though, you have to ensure that each post you want parsed contains YAML front matter.
[gist id=”2296848″]
Inside your layout/default.html, just create the default HTML layout of your page and drop in your liquid tag for your content like so {{ content }}.
That’s it. You now have a Jekyll blog. We’ll get to publishing it in a minute.
Extending Jekyll with Ruby
First, let’s be clear… Ruby is awesome! Jekyll leverages the power of Ruby by allowing you to extend simply by dropping any .rb file into the _plugins directory [3]. For example, when I converted my blog from Ruby to Jekyll, I had a URL scheme that omitted the .html extension from all the URLs. Since I didn’t want any existing URLs to break, I needed to create a liquid tag that would allow me to strip it. It was this easy:
[gist id=”2296858″]
I simply open up Jekyll and add my own custom module to it. Then register_filter with the Liquid templating system and you’re off to the races. To use this just place {{ page_url | remove_extension }} wherever you need the stripped URL. Of course, Jekyll will still generate the files with .html extensions, so serving these URLs is something that you’ll have to configure with your web-server.
I don’t think I need to tell you how useful this is. Almost anything you need to do, you can build yourself. The most common reasons for creating a plugin are generating your HTML based off your own rules (Generators), creating a Liquid tag to alter/modify output (Tags), and filters like the example above. All of these things are as easy as above.
If you’re not that much of a coder, no big deal. There are a bunch of plugins available on the wiki and should be as simple to install as dropping them into your _plugins directory.
Deployment
Alright, all of the work you’ve done so far doesn’t amount to much if you can’t serve your files to your audience. Have no fear, there are a number of ways to get your Jekyll blog to the public. Since Jekyll generates a _site directory with all associated assets/HTML, there isn’t much Jekyll-specific server configuration. Most of the settings are dictated by which web-server you use. For example, in Nginx the configuration for your blog would look like this:
[gist id=’2296866′]
Then just rsync your _site to /var/www/blog and you’re off and running.
However, if you’re a humble hacker on a budget and don’t want to have to host your own site you can use Heroku. Let’s do that.
Heroku & Jekyll Sittin’ in a Tree
The best technique is to use rack-jekyll to create a rack app out of your Jekyll site. It doesn’t require too much setup to work, and once it’s completed you can use Git as both your writing and deployment workflows.
The first thing needed is a rackup file:
[gist id=”2296875″]
Next up is the Gemfile which should look something like below. Be sure to bundle this and check in your Gemfile.lock for deployment.
[gist id=”2296896″]
Once you’ve done that, you should init and commit to setup your git repository.
[gist id=’2296897′]
Since we want Heroku to serve the static files, you’ll have to add the _site directory to your git repository. I found checking-in that many files to be a little unseemly, so I created a separate branch for deployments to keep the master branch clean (manually merging before deploy).
[gist id=”2296898″]
Now just add, commit, and then call heroku create --stack cedar. Once that’s finished, you’ll need to generate your files again (just to be sure they are current) and push to heroku.
[gist id=”2296900″]
You now have a blog running on Heroku!
Conclusions
Since converting my blog to Jekyll, it has been a wonderfully flexible solution to many of the issues that surround creating and managing a blog. There is a tremendous amount of information on Jekyll and many of the people who use it are incredibly helpful and willing to assist. When choosing a new platform, those two facts alone would merit giving Jekyll serious consideration. However, what I found was much more: a solution that was simple, elegant, and powerful.
Creating content has never been easier.
<soapbox>
And that is the crux of the matter…
If you want to create a blerg in Rails or Sinatra, then by all means go for it. I think (scratch that, I know) you’ll find it a rewarding learning experience. I found the things that make Rails and Sinatra amazing frameworks are not just their ability to serve static files, but rather, their ability to create dynamic applications. For a blog:
Don’t waste your time building wide [features], instead build deep [content].
A blog should be simple and flexible. Jekyll helps.
</soapbox>
Thanks for reading. Jekyll has an amazing wiki with tons of information; be sure to check there for additional details not contained in this article.
Jonathan JacksonJonathan Jackson is a Ruby/Rails developer, working in Jacksonville Beach at Hashrocket. He often writes about Ruby development at his blog jonathan-jackson.net, which features articles designed to enlighten newbies and veterens alike. When he's not crunching code, he enjoys gaming, reading, and ultimate frisbee.
