How to Blog with Jekyll

August 9, 2012

Recently, I decided to switch my personal blog over to Jekyll, a blog-aware, static site generator written in Ruby. By design, Jekyll is simple, fast, and not bloated like most CMS. In fact, Jekyll doesn’t need a database to run and there’s no traditional admin panel to create, edit, and manage your posts. Instead, you get to use your favorite text editor and version control system to push changes to your site. Everything lies on your local computer, meaning there’s no chance for data loss due to a faulty database on your server. You also don’t have to worry about constant updates and security flaws.

If you’re willing to hack a little, I’d highly recommend switching over to Jekyll. Sure, you lose the bells and whistles, but you’ll be able to focus on the important part: the writing.

Getting Started with Jekyll and GitHub

Jekyll was developed by GitHub co-founder Tom Preston-Werner, so naturally, GitHub Pages offers free web hosting that you can use to power your Jekyll site. We’ll start off by getting Jekyll set up on your local computer and then pushing it to a new repository on GitHub.

Start off by installing Ruby if you don’t already have it. Then we can update RubyGems and use it to install Jekyll.

$ gem update --system
$ gem install jekyll

You should also go ahead and install RDiscount to process Markdown, which is what Jekyll uses for authoring posts (of course, you can use Textile or HTML if you prefer). By default, Jekyll uses Maraku, but I found it slower and more difficult to use than RDiscount.

$ sudo gem install rdiscount

If you want code syntax highlighting on your blog, you can also install Pygments. You’ll need to install Python to continue.

$ sudo easy_install Pygments

Your local dev environment is now completely setup to run Jekyll. To get your site up and running, all you have to do now is to create a new directory and a new repository on GitHub in the format username.github.com

$ mkdir frankjwu.github.com
$ cd frankjwu.github.com

For the sake of seeing progress, you can create a new index.html file in your new directory and fill it with the following.

<!DOCTYPE html>
<html>
<head>
  <title>Frank Wu</title>
</head>

<body>
  <h1>Hello World!</h1>
</body>
</html>

You can now start your local Jekyll server, navigate to http://localhost:4000, and see your new site!

$ jekyll --server

Push it up to your recently created GitHub directory and you’ll see it up and running on GitHub Pages as well.

$ git init
$ git add .
$ git commit -m "Initial commit"
$ git remote add origin [email protected]:frankjwu/frankjwu.github.com.git
$ git push origin master

It may take around ten minutes for GitHub Pages to fully update.

Configuring Your New Blog

Obviously, you’ll want to do more with your blog than just display a single HTML file. To do so, you’ll need to setup your directory with the basic structure that Jekyll expects:

.
|-- _config.yml
|-- _includes
|-- _layouts
|   |-- default.html
|   `-- post.html
|-- _posts
|   |-- 2007-10-29-why-every-programmer-should-play-nethack.textile
|   `-- 2009-04-26-barcamp-boston-4-roundup.textile
|-- _site
`-- index.html

Simple! All of these folders are fairly self-explanatory, but if you’re unsure what something does, you can read the Jekyll documentation. _config.yml holds your configuration settings, _includes stores partials, _layouts holds templates for displaying your site content, _posts contains your blog posts, _site is automatically generated by Jekyll with your static pages, and index.html is the page that will be displayed at your root URL.

We’ll go ahead and create a simple default.html layout to get started.

<!DOCTYPE html>
<html>
<head>
  <title>{{ page.title }}</title>    
  <!-- You can load CSS files and other meta data -->
</head>
<body>
  <h1>Welcome!</h1>
  {{ content }}
</body>
</html>

Update your index.html file with the following:

---
layout: default
title: Frank Wu
---

You’ll notice that the default layout uses Liquid code to pull the page title and content, giving you some additional flexibility in creating your layouts.

If you’re following the tutorial step-by-step and you do want to use RDiscount and Pygments, go ahead and create your _config.yml file now with the following.

markdown: rdiscount
pygments: true

If you want to use a custom domain, you have to create a CNAME file and put the desired domain name inside it. You will then need to add an A record that points to 204.232.175.78 in your DNS settings.

At this point, you have already created the basic skeleton of your site and simple configuration settings. Jekyll is up and running and all you need now is to start designing the site layout with HTML (infused with Liquid) and CSS. Even if you’re a talented designer, it’s a good idea to fork an existing Jekyll blog to see how they work. You might want to start with forking Tom Preston-Werner’s blog or even mine to get an idea of what to do next.

Writing Posts

Writing new posts is super easy with Jekyll. You just create a new file in the _posts folder in the format “YYYY-MM-DD-post-title.markdown”. Add the necessary YAML information to the top of the post and Jekyll will do everything else for you. Here’s what this post looks like:

---
layout: post
title: How to Blog with Jekyll
---

Recently, I decided to switch my...

I like being able to work with drafts of my posts, so I created an additional _drafts folder and then added this to my .gitignore file to make sure my half-baked posts don’t accidentally appear on my GitHub repository.

$ mkdir _drafts

It’s also a good idea to add your _site directory to your .gitignore. When Jekyll is run, the _site directory is populated with the static pages that make up your site.

If you want to move blog posts from your old blog, the Jekyll gem provides a number of easy migrations for you as well. I’ll briefly run through the Tumblr migrations since that’s what I migrated from, but you can find full instructions for other systems here.

$ mkdir _import
$ gem install sequel mysqlplus
$ gem install nokigiri
$ ruby -rubygems -e 'require "jekyll/migrators/tumblr";
  Jekyll::Tumblr.process("http://www.your_blog_url.com", true)'

The above steps will create a new directory for your imported posts, install the necessary gems for the migrators to work, and then perform the actual data migration from your old blog. After migrating, you might want to clean up the markup in your old posts, especially if you didn’t use Markdown before.

Thoughts

Obviously, Jekyll isn’t for everyone since it requires a bit of familiarity with the terminal, Git, and Liquid markup, but I’m extremely satisfied with the entire system. I love being able to open my text editor to write posts and then previewing everything on my local server before pushing the changes to a GitHub repository. Pages load quickly since they’re just static HTML files and I feel at ease making incremental changes to the live site.

If you’re still not sure, I’d recommend reading Tom Preston-Werner’s “Blogging Like a Hacker” and Paul Stamatiou’s extremely detailed tutorial, “How To: Wordpress to Jekyll”, for some additional inspiration and thoughts.