Introducing Bloggy: A simple way to add a Jekyll blog to any Rails application

One of the most popular tools our customers use to help drive traffic to their site is a company blog. Blogs that are informative and helpful will attract your target audience and bring attention to your website, and more importantly, your work.

Here at Engine Yard, we have found that some of our best sources of traffic are the blog posts written by our team that help educate customers on our product. In particular, there is one blogging platform that has really started to catch on with the hacker community and especially those of us who love Ruby.

Authored by Tom Preston-Warner, Jekyll is an open-source blog-aware static site generator. Unlike Wordpress, Tumblr, Posterous, Blogger and the like, it allows users to write posts in the editor of their choice with the markup they prefer and then commit the posts to git. I use Markdown to write my posts, but many others choose to write their posts in HTML because they were coming from WordPress and it felt more at home.

Currently, there are lots of posts out there detailing how to get started with Jekyll, how to run Jekyll as a Rack application, etc. What I want to talk about is just a little bit different from these posts.

Let’s start with a simple concept. For SEO purposes it is better if your blog runs at http://mydomain.com/blog rather than http://blog.mydomain.com. We can go into detail here later but that’s really for an entirely different post. Again there are numerous ways of accomplishing this task but I want to talk about doing it with Jekyll.

Finding a way to run your blogging platform within your existing application without many changes to the server configuration is a common cost cutting technique for bootstrapping startups, well-funded companies and even public corporations. One thing we know first hand is how time consuming and difficult that has proven to be for many of you over the years.

That’s why I wrote Bloggy. Simply put, Bloggy makes it easy to run a Jekyll blog right within your existing Rails application with no changes to your current configuration on Engine Yard.

Installing and configuring the Bloggy gem

Start by adding

gem ‘bloggy’

to your Gemfile in your repo, then just run

$ bundle

and it should be ready to go for you. Alternatively, you could install it by running

$ gem install bloggy

Once Bloggy is installed, all you need to do to get a working blog up and running is to use the provided Rails generator.

$ rails g jekyll:blog blog

BAM! This just generated your new blog and it’s live at http://yourdomain.com/blog

Go ahead start up your Rails server and check it out.

What Just Happened?

The static HTML generated by Jekyll (the magic behind Bloggy) goes to your public/blog directory, but the rest of the files live at config/jekyll and this is where you will create new posts, change the default look and feel of your blog and make any configuration changes you desire as you get acquainted with Jekyll.

If you’ve never used Jekyll before, you need to familiarize yourself with a few things.

1. Bloggy Generates static HTML from the markdown files that live inside the config/jekyll/_posts directory, so this is where you will create new posts (more on how to make the generation happen later).

2. The default layout of the Bloggy generated blog is found at config/jekyll/_layouts/default.html. This file is plain ole HTML and can be edited to your liking just like you would edit any other HTML file.

3. The config/jekyll/css directory contains, wait for it … your CSS files!

   Configuration and new posts

   If however, you are familiar with Jekyll already you will be delighted to know you can still choose from all of the options you enjoyed with the Jekyll gem previously.

The same familiar config elements of Jekyll can be accessed using the config.yml file that is now neatly tucked away in the config/jekyll directory of your Rails application.

Now that your new blog is installed and serving pages at http://yourdomain.com/blog you probably are thinking: ###“Zach this is great, but how do I write a new blog post? How do I get rid of the test post you provided me?” Those are great questions. I’ll start with the simplest:

1. To get rid of the generated test post, simply delete the file from your config/jekyll/_posts.

$ rm appname/config/jekyll/_posts/2012-04-25-a-test-post.markdown

1. And to create a new post it’s not much more complicated. Just run the Rake task provided with Bloggy, which will automatically generate a post and open it so you can start writing right away.

$ rake np your_post_title

This will by default open up your new post in TextMate. If you don’t have TextMate or prefer another editor you can just change mate on this line at the end of the new_post.rake file located in your appname/lib/tasks directory.

‘mate #{path}' - for example if you wanted to use vim you should use ‘vim #{path}'

Now, if you’re looking carefully at the created post you will notice that your post was named with a slightly different scheme than just your title. This is critical to Jekyll being able to recognize and generate your posts into static HTML files that your application can serve, so please do not change this. For example if you ran that task today your post would look something like this:

2012-05-03-your-post-title.markdown

Feel free to change the date just make sure you leave it in the correct format, but keep in mind that YAML is required at the top of your post (including the dashes) for Jekyll to generate Metadata when generating the final HTML that you will see your posts rendered in. So the top of your file should always look something like this:

layout: post title: A Test Post —

The Rake task provided takes care of that for you but be sure to edit your title and add any other metadata you want included. Other than that, just be sure to change published: false to published: true so Jekyll knows your post is ready to go live on your blog for the world to see. Once you have written, edited and reviewed to your liking all you need to do is another Rake task.

$ rake generate

From there Jekyll will automatically regenerate your posts as static HTML files stored in the public/blog directory and these files will be served from http://yourdomain.com/blog with no additonal Nginx configuration.

You will have to hit CTRL + C on your keyboard after the files are generated to stop the Jekyll server as it wants to stay on and continually look for new posts to generate.

Now from your application directory you can just run a few commands to make sure you have added your changes to git and pushed them to your repo.

$ git add .

$ git commit -m ‘your commit message'

$ git push

Then deploy to Engine Yard using our awesome CLI tool! by running

$ ey deploy

That’s it! It’s really that simple.

So go check out Bloggy and be sure to fork and contribute if you want to see something added to Bloggy that would help you even more!

I have a sample application for you guys to play around with at our Engine Yard GitHub account.

Alternatively, you can just checking it out in action by clicking here.

Happy blogging!