Open Source Musings The thoughts, ideas, and opinions of an open source guy

A non-techie's perspective on blogging with Jekyll

Jekyll logo

As you probably know, I blog quite a bit. Not as much as I should in this space (sorry!), but quite a bit nonetheless.

WordPress is my blogging platform of choice, mainly because it’s powerful and flexible as well as being easy to use. For whatever reason, I find myself investigating other blogging platforms. Sometimes, the proofs of concept that I create for my clients wind up being going concerns.

That happened with two of the blogs I maintain. They were spread across a pair of services that designed for static blogging. There was nothing really wrong with those services, aside from a few limitations that I ran up against.

In the end, I wanted to embrace my inner control freak a bit more.

I didn’t, however, want to create a PHP-based website or use a bulky content management system for the blogs. Instead, I decided to keep things static. After looking at a few static website generators, I went with Jekyll.

I won’t say the transition was completely painless, but it wasn’t too bad. Making that move let me embrace my inner geek a bit, too.

So, what’s Jekyll?

It’s tool for building static blogs and websites. By static, I mean the pages and post are a set of HTML files. You aren’t pulling information from a database or a set of files (in the way, say, WordPress and Joomla! do).

Jekyll is a bit of a techie tool. You use it at the command line, and it follows the write-compile-test workflow that software developers are familiar with. You write you posts, compile your site or blog, and view everything to make sure all is good. After that, you move the site or blog to your web host.

Don’t let that scare you. At its most basic, Jekyll is fairly easy to use. You will, though, need a bit of technical knowledge if decide want to tweak or overhaul site on own.

Using Jekyll

You’ll need to install a few pieces of software before you can start using Jekyll. Those are:

  • Ruby (a scripting language)
  • Ruby Gems (a package manager for Ruby libraries and programs)
  • Node.js (a Javascript runtime)

Then, install Jekyll. The Jekyll website has detailed instructions for installing Jekyll and its dependencies.

Once you’ve done that, grab a theme. You can find themes here:

Now, you’re ready to go.

Building your blog

Or your website. You can use Jekyll for both.

You can either:

  • Create the skeleton of blog or site in your /home directory (Jekyll will create folder for it), or
  • If you’re going to maintain two or more blogs or sites, create a folder for them. Then, build the skeleton in there. I use a folder called Jekyll Sites.

Jekyll sites folder on my laptop

Run the command jekyll new [folder-name]. That command creates a folder, with the name you specify, and populates that folder with a directory structure and some files. That directory structure can be a bit confusing. There are a number of folders and files that you can ignore. I think of them as a black box that lets Jekyll work its magic.

Jekyll site folder structure

There are a few files and folders you need to know about:

  • _config.yml, which I discuss in a moment
  • _posts, where you save your blog posts
  • _site, which is where Jekyll puts the static HTML files and folders that you publish

Remember the theme you downloaded? Unzip it into the folder where your site lives.

You’ll need to edit a couple of files. The main one is named _config.yml, which controls certain aspects of your blog or site. This includes the blog’s title, its metadata, the URL, links to your social media accounts, and more.

Writing posts

You store your post in a folder named _posts. You can write them in Markdown (which is what I do), or use Textile or HTML.

Your posts need to be in a certain format. The file name must include the date the post is published, along with its title. For example, The file must also have a header that looks like this:

Example of a post

The layout: post option in the header is important. It tells Jekyll that this is a blog post. You can also use layout: page to indicate that a file is a page — for example, an About this blog page or a page with your contact information.

Since I blog ahead (or try to), I use the published: false option to tell Jekyll not to generate a blog post from that file.

One of the services where I published a static blog uses a format similar to this, so it’s nothing haven’t done before. I didn’t need to change in way work too much,

The only arduous task was migrating the posts of one of the blogs. The content was already in Markdown, and they all had a Jekyll-like header. However, the format of the header and the way the files were named, was slightly different from what Jekyll looks for. I had to manually change the header in each post and change the file names to match the convention used by Jekyll. That was lot of tedious, manual work: over 230 entries!

Building your site

So you’ve got a post or two. Now what? Open a terminal window, change to the directory containing your blog or site, and run the command jekyll serve. Jekyll compiles your site, and you can view it by going to the URL that appears in the terminal (for example, in a browser. You can view site on your computer to make sure everything is working. If it isn’t, you can fix it.

Or, can just run the command jekyll build. That builds your site or blog, without the option to view it.

Putting your site on the web

Unless you’re running Jekyll on your own web server, that’s something you’ll have to do manually. You can upload the contents of the _site folder to a server using FTP or rsync. Or can host your site on:

For the two blogs and the site I moved over to Jekyll, I’m hosting the site (which rarely changes) on GitHub Pages. The two blogs found a home on S3.

There’s a lot of information on the web about posting a site built with Jekyll on GitHub Pages. One of the better tutorials I found is a Smashing Magazine.

Setting up Amazon S3 as my host was a bit more convoluted. I followed some instructions I found on the web, but they only partly worked. I should have followed Amazon’s walkthrough. Once I got that done, and pointed my domains to the blogs on S3, I got an inexpensive host.

To post your blog or site to S3, you’ll also need to use s3_website utility. Once it’s set up, it will copy only the updated files to S3. That saves a lot of time.

I like using Jekyll, but …

It can be a bit convoluted. It’s definitely not for someone averse to the command line and messing with configuration files. You usually only have to tweak that configuration files once.

If you’re going customize your blog or site, you will need to learn Jekyll’s templating language. That also applies to anyone who wants to create their own themes for Jekyll. Even if you don’t want to create a theme, it can be a bit tricky to modify the one you’re using.

Speaking of themes, you can’t dynamically preview them. If you want to try a new theme with your site or blog, you have to overwrite the old theme with the new one. You’ll lose any modifications made if you decide that you want to go back to the old theme.

You need to be at your computer to write and publish posts or pages. You could, say, have Jekyll running on your home server and log in remotely using SSH. From there, you can edit your content with vi or Emacs, and then publish it. But not everyone does that. I don’t.

Jekyll isn’t for everyone. It isn’t for every blogger. I never expected it to be, and neither should you. That doesn’t mean I won’t keep using it. For what I’m using it for, Jekyll is a good option.

Thoughts? Let's start a conversation on Twitter.

Did you enjoy this post or find it useful? Then please consider supporting this blog with a micropayment via Liberapay. Thanks!