Our experience with Jekyll and Octopress


October 25, 2012

We recently moved from Wordpress to Jekyll for our website because we found it harder to maintain our site with Wordpress. We also hit performance bottlenecks with Wordpress and were clueless on how to fix those. Jekyll made a lot more sense as it uses Ruby, which we are very comfortable with as compared to PHP. And hardly any performance bottlenecks because the entire site is static, and so no DB tuning required :)

What is Jekyll?

Jekyll is a simple, blog aware, static site generator created by Tom Preston-Werner, founder of GitHub. 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 any of your favorite web server. This is also the engine behind GitHub Pages, which you can use to host your website from GitHub source. We chose to use Octopress, a framework built on top of Jekyll. It comes with lot of features such as:

How does it work?

Every page that you create in Jekyll will have the following sections: - YAML frontmatter on top of every file which will contain data in the YAML format which is processed by Jekyll. The mandatory ones are “title” and “layout” which decides the title and layout of the page respectively. - Liquid markup for the templating with the in markdown format or HTML format. There is support for Mustache too. - Layouts for the pages. - Plugins - this is for customizing the content. You can see more details about how to write plugins here.

“Aha” Moments

There were many “Aha” moments throughout the migration, I am putting those top ones which came to my mind while writing.


Bootstrap makes it so much easier to do the regular stuff - modals, navigation bar, tooltips, etc. And with a little more effort you get responsiveness for free.

Asides are the way you can add sidebar to your pages in Octopress. So if you want something to be displayed on the navbar, add a new aside file and include it in your layout. We had the requirement to display certain posts as “featured” and needed to be shown them in all pages. The only thing to do was to add ‘featured: true’ in the YAML front matter of the corresponding posts and create an aside as follows and include it in your layout.

Integrating with comments

It was as simple adding “comments: true” in the posts which you want the comments to be displayed for.

Keeping the blogs as unpublished

Keep “published: false” in the YAML frontmatter of the post. It won’t show up in the post list.

Need to change the way the URL for blogs are being displayed? Just change the permlink in _config.yml

Where things can take time

Figuring out how Jekyll does the magic

It took a while for us to figure out how Jekyll does the “magic”. Getting a hang of the layouts, YAML Front matter, Liquid Templating, Asides in Octopress can take time. If you need to customize, writing the plugins and what type of plugin to write can also take little time initially.

Learning curve for Sass and Twitter bootstrap

As mentioned earlier, Octopress uses Sass and we chose a theme which uses Bootstrap. There would be a learning curve if you are new to both.

Migrating content from Wordpress

There are quiet a few plugins written to migrate data from other blogging platforms including Wordpress. This worked well for blogs, but will not take care of downloading the related images and also the pages other than blogs. We used the tool exitwp, which will try to migrate as much data as possible including downloading of images. But it does not take care of updating the posts with the new URL for the images, so that was a task that we had to take up manually.

Contact Us Form

There are Wordpress plugins that can help you create a contact us form or a suggestion box. But how can you do that for a static website? You’ve two options:

Team Page

As any company’s website, we also needed a team page - A visual index of people and also separate pages of individual profiles. We found an excellent plugin, that seemed to do just what we wanted. But since we had used Octopress, the directory structure was slightly different from what the plugin had expected. So we had to fiddle around with the plugin to understand how it worked and modify it to work for us. In the end, adding a new person to the team was as easy as adding a new yml file for that person.

Our contribution back

We’ve created a plugin for listing posts by a certain author.

Things, I felt, missing


I would highly recommend Jekyll and/or Octopress for creating a company website especially if you are a software development firm comfortable with Ruby. It combines the power of Ruby, Templating and YAML using which it generates a static web site for you. Octopress helps you to quickly layout the foundation for your website on top of which you can easily build. A huge thanks to the awesome Ruby community and GitHub community without whom the entire project might not have been possible.



Update: I’ve written another post about how to use Prose.io and Jenkins for Live Editing and Continuous Deployment.