An Introduction to Jekyll

Chris Shaw

What is Jekyll?

Although widely known as simply a static blog generator, Jekyll is at its core a parsing engine that is bundled as a ruby gem which is used to generate static ‘blog aware’ websites from dynamic components such as markdown, templates, partials and also your own custom components (see the Collections section below).

Jekyll allows you to build website/blog dynamically and then serve it statically without the need for a database or any server-side code. This means the end result is extremely efficient especially with high traffic blogs where traditional dynamic blogging systems such as Wordpress need to employ a lot of tricks and optimisation techniques to run smoothly. In fact, if you were visiting us in 2015, you were viewing a Jekyll site.

We used Jekyll to build our site because it’s quick to develop and deploy, allows us to publish simple blog posts easily and due to its static nature we don’t have to worry about scalability.

Jekyll Serve

To make development even more convenient, Jekyll comes bundled with its own built-in development server so that you can quickly and easily preview your website locally in your browser, without having to build and deploy it.

Jekyll allows you to specify a myriad of configuration options, many of which can be specified as flags on the command line but are usually specified in their own YAML file (_config.yml). Configuration options include things like safe (disables custom plugins and ignores symbolic links) and exclude which allows you to specify files which you don’t Jekyll to convert.

The Liquid Language

There are actually two distinct parsing and processing tasks performed by Jekyll. The first is content parsing which is done with markdown or textile (Markdown being the default). The second is template parsing which is managed by the Liquid tempting language. Liquid has some quirks to its usage that can be confusing so we will go over the basics below.

Jekyll uses the Liquid Tempting Language to execute logic within template files securely - which means there is no security risk on the hosting server.

The main reason behind Jekyll using Liquid is because Shopify (from which Liquid has been extracted) needs to give their customers some freedom of design whilst maintaining the integrity of their servers. The same is true for Github Pages which also use Jekyll.

While Liquids strict nature is a great solution for Shopify and GitHub pages where you have users editing templates, it can make Jekyll development for other projects frustrating at first.

Nevertheless Liquid is used by an impressive array of different companies such as Shopify, GitHiub, Godaddy, Zendesk and About One. You can see a more extensive list on [Liquid's GitHub Wiki](

Layouts (Aka Templates)

Layouts allow you to define templates for page content and can significantly reduce the effort required to maintain a website that needs the flexibility to change often.

Think of them as extension of the include philosophy, except this is more akin to injecting your page content into a common template.

You can also define child layouts which provide another layer in-between the page layout and the content.


Note - As per the Jekyll Documentation "Collections support is unstable and may change. This is an experimental feature and the API may change until the feature stabilises”

Collections in Jekyll are exactly what they sound like - they are essentially groups of objects that share common properties.

With regards to Jekyll itself, collections allow you to define a new type of document that behaves similarly to how Posts and Pages do. The difference is that you can specify additional properties and they have their own namespace.

For example on our website we use a collection of team members. Each team member object contains a name, role, image and bio and could be represented using the following markdown:

name: Chris Shaw

role: Engineer

image: chris-shaw.png

bio: no bio

Every time we need to make a change to our the team list, whether it be adding a new team member or updating someones photo we simply need to make/amend the appropriate collection file without having to delve into our more complicated template code.

We can use a simple for loop on any pages displaying our team collection, meaning we don’t have to write or change any more code for the new member amendments to be displayed.

Restriction and Pitfalls

Some of Jekyll’s features can be constraining by their design. Knowing what they are can allow you to plan around them.

Post Ordering

Ordering blog posts can be a pain as the dates are hard coded into the file names and only chronological and reverse chronological ordering is supported.

You could work around this by making your own Collection of entries to use instead of the inbuilt blog posts and order them by an attribute.

Jekyll Import

When thinking of using Jekyll strictly for blogging purposes it’s common for people to already have an existing blog somewhere with a large amount of content. One of the biggest headaches for a blogger contemplating whether to switch to another system is the logistics of moving their content, or worse the prospect of having to simply ditch it because there is no easy method.

Jekyll tries to make this easy for you by providing users with a separate gem call jekyll-import which can handle content import from most of the common blogging platforms such as Wordpress, Blogger, Tumblr, Joomla, Ghost, Enki and even Behance. There is also general import support for CSV files and RSS feeds.


Jekyll Bootstrap - A guide on how to get a Jekyll blog up and running with GitHub Pages

Related Articles


Back to Technology