Blogging Like a Techie with Jekyll

by: Scott Nesbitt | 03 October 2018

As you probably know, I’ve done a quite a bit of blogging over the years. Most of my blogs have been put out to pasture, but I still post in this space and elsewhere.

Once upon a time, WordPress was my blogging platform of choice. WordPress is powerful and flexible, and it’s fairly easy to use. But WordPress also has a few too many features that I never use, and it requires a bit too much infrastructure for my tastes.

On top of that, I sometimes want to embrace my inner control freak a bit more. Which is why I moved away from WordPress I didn’t, however, switch to a bulky content management system. Instead, I decided to keep things static. After looking at a few static website generators, I went with Jekyll.

While Jekyll can be a bit geeky, it’s a powerful and fairly simple way to build blogs (and websites) in plain text.

So, Just What is Jekyll?

As I mentioned, 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). It’s all plain text.

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:

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.

Crafting Your Blog

Or your website. You can use Jekyll for both.

You can either:

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:

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, 2015-03-26-My-Post.md. 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.

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, http://127.0.0.1:4000/) 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:

I host my Jekyll blogs and site on Amazong S3. Setting up Amazon S3 as my host was a bit 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’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.

Jekyll isn’t for everyone. It isn’t for every blogger. I never expected it to be, and neither should you. But if you want embrace your inner geek a bit and blog in plain text, Jekyll is a good choice.