An introduction to Jekyll

A little while back, whilst trundling the interwebs researching this-that-or-the-other, my interest in maintaining a personal blog peaked again.

I've been through various incarnations throughout the years, swinging violently between constant iteration and refinement to long periods of dormancy and silence.

Around a month ago I decided to revisit it again. I've been doing a lot more writing — which I've enjoyed — so maintaining my own outlet where I could write additional articles was appealing. But to achieve something I was happy with (learing lessons from last time) I'd need to tick off each of the following:

• Keep it simple

  There's no need to over-engineer. Pick the appropriate tools. For example, is it really necessary to have a content management system? Probably not. I may be a MODX developer, but that doesn't mean I need to use it for everything. Developers should always pick tools based on it's suitability, rather than allowing your bias to pre-select a framework.

• Keep it concise

  In part, the forgotten cousin of point #1. In terms of goals, the site should avoid being a "jack of all trades". Content-driven blog? Image-driven portfolio? Pick a side and do it well.

• Keep it open

  By sharing source code I know there's always the possibility of spontaneous peer-review. It's good to be kept on your toes (even if nobody's really looking). It also helps others to learn (which is the point of this particular article, after all).

It was in the pursuit of point #1 that my interest in Jekyll peaked. A simple, blog-aware static site generator, I'd stumbled across Jekyll a while back but never found a use-case for it.

Instead of using a database, Jekyll runs a bunch of raw text files through a Markdown converter and Liquid renderer to generate a complete, static website that is platform independent. As a developer you have the opportunity to build a light-weight, modulated system with little-to-no markup duplication, using all the usual CSS/SASS tools, plus the convenience of deploying your work to any architecture.

In addition to this, GitHub Pages is powered by Jekyll. By pushing your source to the world's most popular code repository you can utilise it as a free hosting platform (custom domain name and all) that generates a static Jekyll site. This also means there's no need to commit the generated HTML to the repo (which is a smarter way of working anyway). So that's point #3 checked-off.

Of course point #2 is down to me. Now that I'm more inclined to write, selecting a "blog aware" platform would appear to be a reasonable move. I don't have the assets required of an image-driven site, and much that it might be prettier to look at, it doesn't actually serve the overall purpose. This time around, it's about substance over style.

Install with RubyGems

So let's take a look at Jekyll in a little more detail. I've lifted some of this information directly from Jekyll's Quick Start guide — which of course you should browse through too.

The best way to install Jekyll is via RubyGems. Over the last year or so I've used a Mac, so in this case it's just a 2-minute job. Windows users should follow this step-by-step guide. Using Jekyll on Windows is not officially supported by the Jekyll team, and while these instructions are featured on the Jekyll website it remains unofficial.

$ gem install jekyll

Create a new project

Once installed, getting a Jekyll project up and running only requires three more commands:

$ jekyll new chrischerrett.github.io
$ cd chrischerrett.github.io
$ jekyll serve --watch

Once the server is running, browse to http://localhost:4000 and you'll see the content of your project's _site folder (when you have one — see below) served as static HTML.

Before we carry on, it's worth noting the configuration options available to you, and which ones to pay attention to from the beginning.

Jekyll allows you to mould your site in any way you want, and it’s thanks to the powerful and flexible configuration options that this is possible. Typically, these options are specified in a _config.yml file placed in your site’s root directory.

You'll see settings in here for title, decsription etc. You can refence any of these settings in your templates using syntax like {{site.author}}. This is good if you want to repeat values throughout your site, like this site does in the {{site.description}} part of the template.

It's important to note that Jekyll will sometimes do some fairly assumptive things, like copying everything in the root directory to the _site folder. There's a good reason for this, and in many cases this is a good thing (e.g. the way I've organised assets into their own folder) but other times you want to exclude specific files or folders from that process. Use the exclude property to define an array of paths that should be omitted. This is especially useful if you're using tools like Gulp.

Directory Structure

To explain the directroy structure in a little more details (seeing as I've just touched upon it), my project is broken down into 5 folders:

• _includes

  These are global HTML files, typically referenced by most (if not all) _layouts. For example there are snippets of HTML in here — like the header and footer — that each template uses. This helps to reduce duplication, and encourages reuse.

• _layouts

  These are essentially "master" templates, but they can also inherit the layout of another. For example I have a default.html layout that is inherited by all the others. This ensures that if I change one part of the default layout, all the other templates get that update too. When creating content you'll define which layout that page or post uses.

• _posts

  This is a special folder reserved for blog articles. The format of the filename (along with some META data called YAML Front Matter) defines the publish date of each post, as well as some other properties, like which of the _layouts to use.

• _site

  This folder is created automatically by Jeykll, so you never need to worry about it's content really. All HTML, CSS and images are copied to this folder. It's this folder that GitHub Pages and http://localhost:4000 will serve when someone browses your site.

• assets

  I've touched on this one already, but basically I just organise all my assets (images, styles and scripts) into my own custom folder. This folder's then copied into _site by Jekyll, but not before the SASS is parsed and CSS compiled.

Content

So that's the structure explained, but what about just "normal" web pages. Where do they go?

For the most part, much of my site's content sits in the root. As an example, there is a markdown file in there called contact.md. Ultimatly, Jekyll will convert this into a HTML file and copy it to the root of the _site folder, giving me a contact page.

At the top of contact.md is the following Front Matter:

---
layout: page
title: Contact
permalink: /contact/
---

This tells Jekyll to use the "page" layout, to give it a title of "Contact" and to assign "/contact/" as it's URL. There's a bunch of extra properties you can assign, but as this site shows, that's all you really need to get going.