Working hard illustration by Ed Clews

Updating my portfolio from from Wordpress to Jekyll

I recently went through the process of giving my website a downgrade. I seemed to spend more and more time updating Wordpress plugins and fannying about in the back end rather than actually sticking up work on it. After reading a couple of articles on static site generators and watching Guil Hernandez’s Treehouse videos I was up for giving it a whirl.

For those unfamiliar with static sites, you create them through Markdown files locally on your desktop and run them through a compiler which spurps out an html site build at the other end. Jekyll has it’s own localhost server that you can run in your browser. It’s quite bare bones and involves using a terminal command to get it up and running, which if you’re not familiar with can be a little daunting at first but it’s relatively easy to do.

There are plenty of Jekyll tutorials about that you can search for - is the best place to start I reckon. There’s also plenty of readymade themes to use if you don’t want to start from scratch, which is what I did.

Getting started

I have my own hosting so I’m using that rather than Github Pages, which is free site hosting if you have a Github account.

I already had an existing Wordpress site that I could take the content from and I had worked out what bits I wanted to trim out - mostly old blog posts and portfolio pages that didn’t really need to be up any more. The site structure and layout would be similar, with my illustration portfolio upfront that linked to their own individual pages that you could also click Next/Previous through, Blog posts in their own section and a separate About. I could retain some of the functions I wanted like running Google…(line truncated)…

After a couple of aborted tries I used this Minimal Mistakes theme which has its own quick start guide. Starting with an existing theme gave me more time to get to grips with the more technical aspects of Jekyll like Front Matter and Liquid rather than having to grind out a new site design from scratch. This theme does enough for me and the author has written plenty of guidance to get going with. He was even quite responsive when I approached him on Twitter a…(line truncated)…

One point I would highlight here is how the different types of pages work. You have Posts, Pages and Collections. Posts and Pages are similar to how Wordpress has them: Posts are content with a date on them and Pages don’t (so you’d use them for things like a Contact or About page). Collections are groups of pages that don’t need dating, but still need grouping together somehow (like for a portfolio). This Explain like I’m five: Jekyll collections post…(line truncated)…

Getting it running

First things first was getting Jekyll installed. I’ve got a Mac laptop and a PC desktop and I like to switch between them when working - I can diddle about on the sofa downstairs then get stuck in on my desktop upstairs. On both of those I have the Github Desktop app installed to sync between computers and a Github account.

On the Mac it’s relatively simple. The biggest obstacle can be getting your head round using the Terminal to download things like Node and Ruby but it’s easy once you do it a few times. Windows isn’t officially supported but there is a guide to installing it and it involved installing a few more programs with names like Chocolatey. After that it’s the same but using the Command Prompt or Powers…(line truncated)…

After that, you can either create a directory and run Jekyll inside it, or use Jekyll itself to create the directory.

The two main commands are:

  • Jekyll serve which starts your local server
  • Jekyll build which makes Jekyll compile your site then put a static version in the /site directory

Using Markdown, Liquid and Front Matter.

These are the three main things that do the business in Jekyll.

Markdown is simple text formatting that Jekyll converts to html. Rather than html tags it uses simpler bits like a hash at the start of a line to represent a header or double asterisk to do bold. When the site is compiled it converts the markdown to html then sticks it in a sitefolder to upload to your server. For example:

**These asterisks make this sentence bold**

which makes: These asterisks make this sentence bold

You can also mix html tags in your Markdown but if you’re trying to keep it minimal stick to the Markdown.

Liquid is the variable that loops through and draws in data for the site. At a basic level it automates tasks that Jekyll needs to do in order to render out the site as html after you compile it. you’ll probably use it to get blog posts but there’s buckets more you can do with it. Say you have a set of things like different types of cakes. Liquid can get those cakes for you and show them in any particular way you want like in a list. If you’ve tinkered with Javascript or any other coding then you’ll rec…(line truncated)…

Front Matter is a bit of code that goes at the start of your page that you can define what is the layout, permalink, title and other characteristics of your post. For example:

layout: post
title: Blog post title goes here

tells Jekyll that the layout ‘post’ will be used which makes it use a specific layout, and gives it a title of ‘Blog post title goes here’. You can also shove in any other meta data like post excerpts, tags etc, so it’s similar to setting up a Wordpress post except they’re in different places.

Coding hard from Wordpress to Jekyll illustration by Ed Clews

Is Jekyll for me?

For the moment, yes. It’s a minimal fuss setup that I can use easily and doesn’t need much upkeep. Using it has been a nice little learning exercise in working with something I don’t usually get a chance to have a go on and I’ve done some new things along the way. If you’re ok with monkeying about with Wordpress templates and bits of code, you can pick Jekyll up. Have a go with a template first, it will take you a couple of pops before you get your head around what’s the best approach to use to rework your …(line truncated)…

I’ll probably do a follow up in six months or so to see how I’ve been getting along with it. I may be cursing the very day I heard of it (it’s unlikely though).

What Jekyll can do vs Wordpress out of the box

  • Get a blog or site up and running quickly
  • No fannying about with databases
  • Can use an existing Jekyll theme and rework it for your own use

What can’t it do like Wordpress

  • Less user friendly without a WYSIWYG interface although this is available as a plugin
  • It is SEO friendly but writing a post out without the benefit of something like the Yoast SEO plugin can be a bit of loss if you’re used to using that as a guide
  • There is some automation of things like tags, categories and recommended posts but there will be some fiddling to get it to work the way you want it

What I learned / odd problems / bits I changed

  • Jekyll can be finicky with odd characters. For instance I used a : or - in a Front Matter title and it threw it. You can always check in the Terminal/Powershell to see if something has upset it
  • There seemed to be an issue with the Next/Previous not displaying the theme colours and having white text. I found the issue was that I had set the locale to “en-GB” instead of “en-UK” in the config.yml file
  • There is a Wordpress plugin to extract and convert your posts to the Jekyll Markdown format but I just couldn’t get the bugger to work properly
  • Don’t forget to uncomment your site in the config.yml file, this caught me out a couple of times trying to find the changes I’d just made to the page when in fact I was looking at the live site rather than the local one
  • Get ready to do a lot of old link checking in Webmaster Tools and 301 redirects especially if your old Wordpress site managed the htaccess file

Watch this video series by Thomas Bradley, it explains Jekyll well in small chunks.


Updated: - written by Ed Clews

Leave a Comment

Subscribe to my mailing list

* indicates required