Getting started with Jekyll

6 February 2017

This is a guide to Jekyll. If you are brand new to it, you may want to skip to ‘Installing Jekyll’. If you are upgrading, you may want to start with ‘Upgrading from an old version’

Why Jekyll

I absolutely love Jekyll for static web pages, simple sites, landing pages, whatever! It is simple, yet flexible, and endlessly customizable.

What I really, really love about Jekyll is how simple it is to host and deploy. Simply push to Github pages, and you can host your site for free. You can even redirect the site to your own domain name and stick a simple CNAME doc at the root of your project so Github knows how to redirect your site.

What I love even more is that, as a blogging platform, it is pretty secure as well. I spent years in WordPress land, hosting my personal site and blog there. I think WordPress still has a place in the blogosphere, but I personally got tired of the plugins and potential security vulnerabilities. With Jekyll, since it’s all static pages, there is no login or permissions I have to deal with. And again, because it’s all static files, loadtimes are pretty fast as well.

There’s just nothing I love more than Jekyll for static sites.

The times, they are a’changing: Upgrading from an old version of Jekyll

I have been using Jekyll for a few years now. I started with version 1.9 something, as most people. I was used to things a certain way. The latest version of Jekyll (version 3.x.x) has changed quite a few things, most notably, theme files are obfuscated from the get-go, which I found confusing at first. This move was done in favor of treating themes as gems, and I think it absolutely makes sense, but it was a little hard to understand at first, especially since there’s not a lot of documentation around it.

If you’re coming from an older version of Jekyll, know this:

I am pretty much using everything Jekyll ships with. The only plugin I currently use is jekyll-feed.

Installing Jekyll

If you’re new to Jekyll and are starting for the first time, this is where you should start reading!

First, you will want to make sure you have Ruby installed. I personally like to make sure I have the latest version of Ruby. I use rbenv to manage my Ruby versions. You may want to install rbenv and update to the latest version of Ruby before starting.

With Ruby taken care of, you will want to install bundler and then jekyll itself.

$ gem install bundler
$ gem install jekyll

For my personal machine, I like to just install Jekyll globally like that. With Jekyll now installed, start a new Jekyll project with jekyll new title-of-your-site. Once that is created, cd into your site.

You will now see the following structure:

If you were using an older version of Jekyll, this may seem sparse! More on this later.

Let’s look at each component:

.gitignore: self-explanatory, but if you’re not familiar with this, this file essentially means “these are the files git will not put into version control”. You want to keep things like your Gemfile.lock in here, as version controlling that can cause gnarly git conflicts when merging.

Gemfile: If you’re not familiar with Ruby, this is where you define which Ruby gems your Jekyll site needs to run. This is where you would define a gem to later include in your config.yml file.

_config.yml: This is the lifeblood of your Jekyll site, and where all site-wide settings reside. This is where you define stuff like what your permalinks look like, what your site tagline is, and set site-wide variables, like social media handles. You will have to restart your Jekyll server when you make changes to this file if you want to see those changes reflected in your build.

_posts folder: any folder that starts with _ means essentially that this is a “collection of things” and things inside this collection live under the same group. By default, Jekyll comes with _posts for, well, your blog posts. You must place your blog posts inside the _posts folders for Jekyll to know they are blog posts. All posts must have a date in the file name and follow this convention: and are sample pages. Pages in Jekyll are typically markdown files, and Jekyll comes with sample about and index pages. It is not uncommon for the index page to remain empty.

Customizing the look and feel

In the new version of Jekyll, themes are now gems. As such, files necessary for theme are now installed with the gem, and are therefore “obfuscated”, per se.

Jekyll already comes with a theme called “Minima” installed, which can be a good starting point for customization. If you want to customize or override certain elements of the Minima theme, you can bundle show minima to view the files that comprise the theme. You can then create the necessary files on your end to override theme settings.

A Jekyll theme is pretty much comprised of:

Creating your own theme

I chose to create my own theme from scratch, so I ran the following command: jekyll new-theme <THEME-NAME>. This generated all the files I needed to work on my theme, so I then copy and pasted them into my Jekyll site. It just helps me see what I am doing better.

Before you start modifying, you will need to tell Jekyll not to use a theme, and remove references to that theme from your working site. To do this, go to _config.yml and remove the line theme: minima.

If you try to jekyll serve now, you will get a build error:

Could not locate the included file 'icon-github.html'

There is a reference to this icon in the page generated by Jekyll by default when you run jekyll new <SITE>. Just delete the content from the file and leave it blank for now, and that should get rid of that error so you can start working on your theme.

Working with collections

Collections in Jekyll are awesome! They allow you to create content in a more “compact” way, which you can then access later. An example of how I used collections:

You’ll notice in this site, I have a “Talks” section. To do this, I create a Talks collection by adding the following to my _config.yml file:

    output: true
    permalinks: /:collection/:talk

Output: true means you want Jekyll to generate standalone pages for each item in the collection. This allows me to link to each talk individually via the permalink settings I choose (see above).

I then created a talks.html template, which I placed in my _layouts folder. In the template, I call each talk as so:

    <h3><a href="/talks/level-up-your-gif-game.html">Level up your GIF game</a></h3>
    <img src="/assets/images/talks/level-up.png">
    <p>CSS Dev Conf 2016</p>
    <p>A exploration of the history of the GIF, how to best use GIFs in the workplace, and the best GIF workflows.</p>
    <h3><a href="/talks/zero-to-api-hero.html">Zero to API Hero: Consuming APIs Like a Pro</a></h3>
    <img src="/assets/images/talks/api-hero.png">
    <p>RailsConf 2016</p>
    <p>Primer for new developers on how to work with 3rd party APIs.</p>

You can then create a _talks folder (it has to follow that convention) and now Jekyll knows that every file in that folder is a talk. Each talk is a simple markdown file. I followed the same steps for creating the portfolio pages in this site.

Collections make it incredibly simple for you to continue to add a variety of content to your site, and keep all the content neatly organized.

Writing posts

A post is nothing but a markdown file that follows a specific naming convention: They must be placed in the, you guessed it, _posts folder. Posts need the date, otherwise Jekyll does not recognize the post as a post.

It can be tedious to have to write out this convention every time you want to write a post. Lucky for us, Jekyll is built in Ruby, so we can write a Rake task to handle post creation for us!

My Rakefile essentially asks you for the title of the post, the category, and then takes the input and formats it correctly, generating the file automatically. All I have to do is then open it in a text editor. (Full disclosure, I adapted this script from somewhere else on the internet.)


Deploying is free if you host with Github pages. To do this, all you have to do is create a branch of your repository and name it gh-pages. When you push your changes to Github, Github will automatically build the pages for you. Just make sure you are pushing to origin gh-pages when you want to publish your changes.

If you want a custom domain, simply add a CNAME file with your domain on it at the root of your repository. Point your domain’s A record to Github and voila! (This is the old way to do it, but I still do it this way.)

You can also simply go to the Settings page of your repository, and under “Options”, scroll down to “Github pages” and add your custom domain there.

Working with Jekyll is so simple now, I seriously don’t understand why anyone would choose anything else for their personal site. Deploying is a breeze, and your site is endlessly customizable.