Static Website Generation with Jekyll
What is a Jekyll and why should I care?

21 September 2016

I have a blog website (chances are you’re currently looking at it), which I put together using Jekyll. When I tell people this, they usually respond by asking “Jekyll? What’s that?”

I would like to write a quick post to address that.

What is Jekyll?

Jekyll is a tool for compiling static websites. As is usually the case for a compiler, you put together a directory full of source code files, you run Jekyll from the command line, and you get a static website out that you can deploy to your favourite webserver.

What is a static website? As a rule of thumb, this would be a website that doesn’t have any scripts that need to run on the server, and doesn’t need to connect to a database to work. All of your content is wrapped up in files, probably a mixture of HTML, CSS, and JavaScript. This means that the webserver you are deploying to only has one job: to take the files that you give it (the static website that Jekyll produced) and return any files the end user’s web browser requests.

Jekyll itself has an emphasis on managing your website or blog, and its content, in the same way that a software developer might manage source code. Each page is a text file. When you compile, the file is run through a templating engine that lets you do things like reuse common chunks of code, and go between different markup languages.

In my blog, each post is a Markdown file. I write a new blog post by creating a new file in the appropriate folder, and just start writing Markdown. Jekyll also supports being extended with plugins, so I’m also experimenting with writing posts using Emacs org-mode instead of Markdown.

Show me some code!

A post might look something like this:

---
layout: post
title: Hello world
tagline: What an example!
---

This is markdown
----------------

A paragraph

```js
console.log('A code block');
```

The post referred to a layout called “post”. The post layout might look something like this:

---
layout: default
---
<div class="row post-full">
  <div class="col-xs-12 col-lg-push-2 col-lg-8">
    <h1>
      {{ page.title }} <!-- the variable called title is injected here -->
      <!-- then we inject the tagline (if we have one) -->
      {% if page.tagline %}<br/><small>{{page.tagline}}</small>{% endif %}
    </h1>

    <div class="date">
      <!-- The pipe passes the date variable to a filter to make it a nicely
      formatted string -->
      <span>{{ page.date | date_to_long_string }}</span>
    </div>
    <div class="content">
      {{ content }} <!-- the post is injected here -->
    </div>

    <hr>
    <!-- the code for including Disqus is in a different file, and included here -->
    {% include disqus.html %}
  </div>
</div>

Everywhere that you see a {{ }} or {% %} is going to be transformed by Jekyll in some way.

The post layout also references a layout. At the very top, you’d expect the default template to have your html, head and body tags, which would be the same for every page.

Anything that isn’t a Jekyll template is just copied by the Jekyll compile step, so you include assets by just having them in the folder structure that you want them in.

Why should I care about Jekyll?

If you are a software developer, like me, you have probably gotten fairly good at managing text files. I like using Emacs for writing things in general. I like committing content that I care about to version control, and backing it up. With Jekyll, all of the content living in text files makes all of these things very easy.

Another advantage that static websites have is that they are really cheap to host (with prices starting from free, if you go for something like Github Pages). I personally host this site with Hostking, since their smallest package was the cheapest one that met my needs.

The normal downside of static websites is the repeated content. The navbar at the top of this page, for example. This is where Jekyll really helps. You define common code once, and reference it where you need it. Jekyll copies it everywhere that it’s needed, so you don’t need to be running any scripts to do that on your webserver, and you only need to update it in one place if it changes.

What doesn’t mix well with Jekyll?

If the content is going to be primarily written by somebody who prefers to use a WYSIWYG editor, then Jekyll is not for you. Jekyll exists because some people (like me) prefer working in plain text. If that isn’t you, or the person you’re setting the site up for, then consider something that provides an admin interface.

Jekyll is amazing for problems where you don’t expect user generated content. Unfortunately, if user interactions with your site is part of the core functionality, you might want to consider something more dynamic. You can still fake this to an extent. The comments on my blog are hosted through Disqus, which means that all calls to load comments or show existing comments goes to Disqus’ server, not to mine. For my blog, I’m ok with this solution.

On this blog, I’ve talked about Angular JS before. I would probably never mix Angular and Jekyll. This is mostly because Angular solves the same problems that Jekyll solves in a different way. Both are good tools, but there wouldn’t be additional benefit from combining them.

Jekyll is great, but if the problem you’re trying to solve doesn’t fit well with static websites, don’t use it. I’m a believer in knowing several tools, and at least trying to fit a tool to a problem (although I will admit this isn’t easy going into a new project).

I’m sold! How do I get one?

Jekyll’s website is https://jekyllrb.com. There they have guides to help you get it installed on your machine and get started.

I’m stuck! Where can I get help?

Jekyll is fairly popular in the open source world, so typing your problem into Google or Stack Overflow with the work “Jekyll” will work well. Otherwise, there are these links:

It works on my machine

Jekyll has been working well for me. I’ve set up two websites using it, my blog and a website for my wife’s art. It’s generally been a good experience for me, and fits well into the way I want to work. If you think it might be a good fit for a problem you’re working on, why not give it a go?