Ramona Harrison

How I Built My Blog with Jekyll and GitHub Pages

Mar 9, 2015
8 minute read

This site is built with Jekyll and GitHub Pages. In this post, I’ll talk about what that means and how you can create your own free, customizable blog using these tools.

Jekyll is an open-source generator for creating simple websites and blogs. You write content in Markdown. Jekyll takes that content, runs it through a template, and produces a static HTML/CSS website. If it seems mysterious now, don’t worry. Once you start playing around with Jekyll things become clearer. Jekyll is the engine behind GitHub Pages.

GitHub Pages is a free service that allows GitHub users to create their own website located at the URL http://yourusername.github.io. To activate GitHub Pages, all you need to do is create a repository in your account named yourusername.github.io. GitHub will recognize that you’re creating a website and serve files in this repository automatically.

I chose Jekyll because…

  • Jekyll and GitHub Pages are free. No need to pay for hosting.
  • Jekyll is simple. All of my posts live as .md files in a folder on my computer. When I want to create a new post, I just open a text editor. When I’m ready to put that post online, I just use git to push it.
  • Jekyll is customizable. There are a ton of nice themes out there. You can modify them. You can create your own theme from scratch.
  • Disqus for commenting.
  • Supports lots of plugins.
  • Your content belongs to you.
  • No ads.

How to Create a Blog

Jekyll is written in Ruby, but knowing Ruby is absolutely not a prerequisite to get your blog up and running. These are the steps I followed on my MacBook running OS X Yosemite. I was doing research at the same time, so it took me about 2 hours from start to finish. It may take more or less time depending on the theme you choose and if you run into any unexpected errors.

1) Get the tools

We’ll be doing a lot of work in the terminal. Let’s make sure we have all the tools we need:

  • Ruby. OS X Yosemite comes preinstalled with Ruby. In terminal, type ruby -v . If you have Ruby you should see a version number, like ruby 2.2.0p0 (2014-12-25 revision 49005) [x86_64-darwin14] . If not, follow the link to install.
  • RubyGems. Type gem -v . You should get back a version number, like 2.4.6 . Otherwise, follow the link to install RubyGems.
  • NodeJS. Type node -v . If you don’t see a version number, install NodeJS.

2) Install Jekyll using RubyGems

RubyGems is a package manager that makes it easy to download and install Ruby programs. We’re going to use RubyGems to install Jekyll.

  • In terminal, run the command gem install jekyll
  • You now have Jekyll installed on your local system!

3) Choose a theme and fork it to your own repository

Here comes the fun part. It’s time to choose a theme and fork it to your own repository on GitHub. (At this point, if you don’t have a GitHub account, you’ll want to create one)

  • Search for a theme online. I found my theme at jekyllthemes.org. You can find even more by googling ‘jekyll themes’. You can always change your theme down the road.
  • Once you’ve found a theme you like, go to its GitHub repository.
  • In the upper left corner, click on the 'Fork’ button. This will create your own forked copy of the repository.
  • After forking, click on the 'Settings’ button midway down the page on the right side. You’ll see a box to rename your new repository. Change the name to yourusername.github.io (for example, ramonaharrison.github.io) and click the 'Rename’ button.

4) Clone the forked copy to your local computer

  • Decide where on your computer you want the blog files to live. I keep mine in the directory ~/Documents/coding/, but it’s totally up to you to decide where you want the files to be.
  • Use the terminal to cd to your chosen directory.
  • Clone the forked repository: git clone git@github.com:yourusername/yourusername.github.io.git

5) Edit your _config.yml file

  • Now, in terminal, cd into the cloned directory.
  • Type ls . These files are the framework of your Jekyll blog.
  • For now, we’re going to focus on _config.yml. This file contains some basic information about your blog, such as title, author (you), URL, your email, twitter and GitHub links.
  • Open the file in nano: nano _config.yml
  • Update the header at the top of the file with your information. Save with control+o and exit nano with control+x.

6) Create and preview your first post

  • At this point, it may be easier to use a text editor like Atom to manage your posts. You can use TextEdit as well, just make sure that your settings are on 'plain-text’.
  • Your blog posts live in the _posts folder. Navigate into it.
  • You should see some sample posts that came with your theme. Notice the naming convention. Jekyll posts are always named yyyy-mm-dd-title-of-the-post.md. Pick one and open it up in a text editor.
  • At the top of the file is a header with some information about the post. For example, the header on the post I’m writing now looks like:
---
layout:     post
title:      How I Built My Blog with Jekyll and GitHub Pages
date:       2015-03-09 12:31:19
summary:    A overview of the Jekyll framework and walkthrough of how I created my blog on GitHub pages.
categories: jekyll pixyll technical git github
published: true
---
  • Every Jekyll post you create will include a similar header.
  • Let’s create a test post: in the _posts directory create a new file called 2015-03-09-my-first-jekyll-post.md and open it with your text editor.
  • Create a header:
---
layout:     post
title:      My First Jekyll Post
date:       2015-03-09 12:00:00
summary:    This is a test post.
categories: jekyll testing
published: true
---
  • As you might have guessed, published: sets whether or not the post is listed on your blog. If you are working on a new entry that you don’t want to share yet, or trying to hide but not delete an old entry, you can set published: false. Keep in mind that the content of a 'false’ post is still stored in your public GitHub repository, so this may not be the best method for storing something you really want to keep secret.
  • Below your header, add a short body to your post. You can use Markdown to format it (for example create headers, lists, links, or code blocks). Here’s my complete sample post:
---
layout:     post
title:      My First Jekyll Post
date:       2015-03-09 12:00:00
summary:    This is a test post.
categories: jekyll testing
published: true
---

### Check it out!

This is my sample Jekyll post. My next steps will be:
 * Save it
 * Push it to GitHub
 * Check it out in my browser

7) Push your test post and view it online!

  • After you’ve saved your file, you can preview it on your own computer before pushing to GitHub. To do this, use the terminal to navigate to the blog’s main directory and type jekyll serve.
  • Leave the process running and open a web browser. Go to localhost:4000. If everything’s gone well, you should see a preview of the blog in your browser. You can click on your test post to preview it.
  • Go back to the terminal and kill jekyll with control+c.
  • Now it’s time to push everything to GitHub and make it live:
$ git add .
$ git commit -m "Added test post"
$ git push origin master
  • Visit yourusername.github.io to see your blog in action!

When you’re ready, you can delete the sample posts and start pushing your own content. Follow the process in steps 6-7 anytime to create a new post. When I write a post, I like to keep open my text editor, a browser at localhost:4000, and a terminal window running jekyll serve. That way, as I’m editing, I can see my progress simply by saving the file and refreshing the browser.

More Resources