Migrating to Jekyll: the how and the why

April 2014 ยท 8 minute read

As a few of you may have noticed, I recently migrated this website over to Jekyll (or Octopress to be more precise. More on that later). Today I want to talk about what Jekyll is, why I chose it and give you a brief overview how my set up works.
I’ll probably post a few more detailed articles later that explain how I did certain things and why I opted for one plugin or another. This article is intended to be a more broad, less technical overview.

What is Jekyll?

Jekyll is basically a ruby based website generator. It takes your written posts (in markdown format) plus a few templates/files - basically how the website will look like - and generates a static, polished website.
The resulting, generated website is so simple, it can literally be deployed anywhere. Even on Github or your old-school web hosting account from the last century. No PHP, Java, Ruby or even databases required. All you need is a folder to put the html files and all the assets into (like images, css files, javascripts …).
Meanwhile, it stays 100% customizable. You control every detail of the resulting page. Don’t like the order of the elements of your sidebar? Just change one (HTML) file, regenrate your site and that’s it.
No complicated fiddling within complex third-party (PHP) plugins. No clunky administration interface.
Use whatever app you like to use to edit your templates.
And the best thing: Once you’ve set it all up (which may require a significant amount of work…), posting a new page or article can be as simple as dropping a markdown file into a Dropbox folder!

That all comes, of course, at a cost.
First of all, you need quite a few skills to pull this off. You surely don’t need to be a full-fledged developer to set up your very own Jekyll/Octopress site. In fact there’s even a service that helps you with that. However, you need at least basic skills in a few things:

  • HTML
  • CSS
  • JS
  • Ruby
  • Markdown/Textile
  • Command line

Any additional skills actually help to make things easier, like Sass, git or bash scripting.

Overall, setting up a Jekyll site isn’t something an average person can or should do. Once it’s set up (and if it’s done right), everybody can post an article as long as he/she is able to write in markdown, textile or html.
For people like me, however, people who like to fiddle with things, figure things out, make them their own, it’s almost perfect.

The Why

Why would someone in his right mind invest so much time and effort in such a low-level solution that requires a lot of manual work to set up?

For me, it comes down to 4 major points:

  • ease of posting new articles
  • simplicity and speed
  • flexibility to easily change any part of the system
  • having fun when figuring things out

Especially the first point was a pretty big one for me. I don’t consider myself a writer. Although people have repeatedly told me I was good at it, it never came easy for me. Writing seems to be one of the least favorite parts of my work. I never know what to write and I also seem to take a long time to write even the smallest articles. Well, maybe part of the reason for that is procrastination…

That being said, writing is becoming an increasingly important part of my live and I can’t really say I hate that fact. The more I learn, the more I think about things, the more I seek an outlet for my thoughts on different topics or a way to teach other people how to do things. Probably one of the reasons I love being on podcasts so much…

And every single step I can remove from the process of writing, helps me to enjoy it a little bit more. Wordpress, and most other CMSs add a lot of unnecessary stuff:
I’m already writing my articles in markdown. Why do I need a fancy WYSIWYG editor to write? And even if I can directly write in markdown I usually still need to convert it to html, which (for some weird) reason only seems to work 50% of the time.

With Jekyll, all I have to do is add a little header to my articles (called “front matter”), and literally drop it into a folder once I’m done writing. That’s it. Everything else happens automagically.

Which brings me to my second point: simplicity and speed.
Having a static, HTML based, website is much faster than most if not any CMSs. Even if you add things like caches. With a CMS, the web server still needs to run at least a few lines of code to decide, that it can serve a cached version of the site. That may even involve a few queries against some kind of database.
With Jekyll, all I have is a bunch of HTML files. Any dumb web server can serve those and has been good at it for the last 15-20 years. Add a simple, well-thought caching strategy to it and your site can be really, really fast. You can even drop the entire site (or parts of it) on a CDN and serve millions or billions of users without even loosing a night’s sleep over it. That doesn’t mean that your website has to be a static, boring mess. Nowadays, a lot can be done on the client-side with javascript using frameworks like jQuery, angular.js, knockout.js or any of the other myriad cool frameworks.

The last two points are equally important to me, being a developer and liking to fiddle with things. It’s fun, I learn a lot and I can adapt whatever my setup is to the ever-changing whims of my live.

The How

As I mentioned before, I don’t want to spend a lot of time on describing how I’ve done things. I’ll probably write additional articles in the coming months describing in more detail how certain things work, the plugins I’ve used and the changes I had to make to them (if any). However, I wanted to give you at least a broad idea how my setup looks like.

As I already mentioned, I’m using Octopress to generate my site. Octopress is basically a set of tools around Jekyll that makes it a little nicer to use. Not that Jekyll would be difficult to use, Octopress just adds a few nice tools. So, for simplicity reasons, I’ll be talking about Jekyll when describing my setup. You can do this with plain Jekyll, or use Octopress 3.0 like I did.

Jekyll is basically a set of Ruby files. Once you’ve installed it on your system, you create your “project”: a bunch of folders where your templates, posts, images, pages and everything Jekyll needs to generate your site will live in. If you want to know more about this, the Jekyll documentation is a lot more detailed.
Here’s how my directory structure looks like:

Octopress directory structure

Octopress directory structure

I have committed this to a private repository on Github which is also synced to a dropbox folder. That way, I get both versioning through git and the ease of use (especially on iOS) which Dropbox provides. Every change I do in my Dropbox Folder results in a git commit and vice versa. And every time I commit to my git repository, my build server generates and publishes a new version of my website. Achieving this wasn’t easy, but having your own server definitely helps.

As you can imagine, I’m using quite a few plugins to extend/customize/enhance the core functionality of Jekyll. Some of them have been customized to my needs, some of them are still in pristine condition. Here’s the list:

There are also a few additional libraries I’ve used. thinks like:

  • Sass for the css part
  • Compass to generate the sass files
  • Fancybox

Migrating to Jekyll

Previously, all my websites were running on self-hosted Wordpress installations. Especially my Casual Kitchen site had a lot of pre-existing content that I wanted to migrate over to Jekyll. This, however, was a little bit more difficult than just converting the HTML content to markdown.
Due to the fact, that I was using a few, very special plugins, my content wasn’t pure HTML. That’s why I used a customized version of exitwp and also a little bit of bash scripting magic to convert and clean up my posts and pages.

Your mileage might vary and especially if you’re using a standard Wordpress installation (or Wordpress.com) or any of the other supported blogging platforms that can be migrated to Jekyll, things might be a lot easier for you.
And you’re doing this only once!

That’s it. Now you hopefully have an idea what I did and why.

If you have any questions regarding my setup, or need any help, feel free to contact me. You can also book me, if you need more of my time!