How To Change Your Jekyll Blog Theme

Read Time: 14 mins Languages:

Jekyll is a static site generation system that lets you take plain text files and convert them into a sophisticated blog, without needing to worry about the databases, security issues, updates and other complications that can come along with many CMSs and blogging platforms.

Similarly to most site management systems, it's possible to use themes on Jekyll sites. However at the moment, Jekyll doesn't use themes in quite the way you might be used to.

Right now Jekyll themes are not self contained packages need to be applied through an installer. When you download a Jekyll theme you'll actually also download all the files required to run an entire Jekyll site.

This will be changing in a future version of Jekyll, but for now you'll need to know how to deal with the fact Jekyll themes come with a whole site attached to them.

In this tutorial we'll go through setting up a Jekyll theme from the very beginning, starting with some basic installation advice, stepping through how to familiarize yourself with a new theme's features, and going through tips on setting up a new site or re-theming an existing one.

Let's begin!

Jekyll on Envato Market

The Jekyll category on Envato Market has a bunch of themes ranging from $19 to $24. Later on, we'll be using "Writer" and "Astro" (the two current top sellers) to demonstrate installation.

jekyll on Themeforest — Jekyll themes on Envato Market

Installing Jekyll

Jekyll is designed to be managed offline on your own computer, built into a static HTML site, then deployed. When adding content the basic process is to create a markdown file, add some front matter at the top, fill out the rest of the file out with content, then rebuild your site.

Once your site is built you can deploy it in any way you choose, be it via FTP or git commands. We won't be focusing on deployment in this tutorial however, so if you'd like to read more about the topic please visit the Jekyll documentation.

Rather, we will be focusing on the portion of your Jekyll site setup process that happens offline on your computer, which all starts with installation.

Prerequisites

Working with Jekyll does involve a little bit of command line usage, but if you've never worked with command line before don't let that put you off. I recommend running through some entries in our The Command Line for Web Design tutorial series to get comfortable.

If your computer is running Windows, unfortunately Jekyll is not officially supported. That doesn't mean you can't make it work, but you may have to jump a few hurdles. If you'd like to take a run at using Jekyll on Windows check out details in the Jekyll documentation.

Otherwise, if you're on Mac OS X, Linux or Unix you'll need to ensure you have these prerequisites installed:

Ruby (preinstalled on Macs)
Ruby Gems (for Ruby package management)

To check if you have Ruby installed run the command ruby -v. To check for Ruby Gems run gem -v. In both cases these commands are checking for a version number so as long as you see a number returned in your terminal you're good to go.

We'll be working with Jekyll 3.1.x so you won't require NodeJS or Python as is mentioned on the Jekyll installation documentation page.

Running Jekyll Install

Now, to install Jekyll onto your computer run the command:gem install jekyll

If you see a message that says you don't have write permissions, preface the command withsudo and enter your password when prompted.

You'll then see a few lines print out in the terminal showing the installation process being run. When it says "1 gem installed" you're done.

Create a Default Jekyll Site

Let's quickly create a Jekyll site so you can see what it looks like in its default, un-themed state and familiarize yourself with its file and folder structure. Create a folder to house the site, then open a terminal pointed to the folder and run:jekyll new .

Note: if at some point you want to create a new Jekyll site in s subfolder instead use the command:jekyll new subfolder_name

When the site setup is complete you'll see a message in your terminal saying"New jekyll site installed in <path>". At this point, inside your folder you should see the standard contents of a Jekyll site.

Now run the commandjekyll serve to get your site up and running offline.

When you see the message "Server running... press ctrl-c to stop" in your terminal, you can go the address http://localhost:4000 in a browser and check out the default Jekyll site.

Now that you've seen what the file and folder structure of a default Jekyll site looks like, as well as its un-themed state, you'll have a better understanding of what you're seeing inside a typical Jekyll theme download.

Quick Demo New Themes

As you know from what we've talked about in this tutorial so far, Jekyll themes currently come with all the files needed to run an entire site. And as you saw in the last section, once you have all those files you can run jekyll serve to enable viewing that site in a browser.

This means that when you download a new Jekyll theme you can just extract it, run jekyll serve and demo the theme on a fully functional Jekyll site right away. Many themes will even come with demo content already included.

Let's look at some examples using the themes "Writer" and "Astro", (or any you prefer).

Once extracted, search through through the theme's structure until you find the root folder housing all the files of a Jekyll site. You should be able to recognize this folder from your default Jekyll install earlier. Look for things like the _config.yml file, the _includes directory and so on.

Then open up a terminal inside the folder and run jekyll serve.

If all is successful you'll see the message "Server address: " with a URL displayed toward the end of the terminal. Copy and paste this URL into a browser and you should see a demo of your new theme.

Missing Dependency?

In some cases you might see an error message when you try running jekyll serve. If this happens look to see if the message is complaining of a missing dependency, i.e. something the theme needs in order to function is missing from your setup.

In this example, you can see in the red error text that the "jekyll-paginate" gem is missing:

A quick Google search turns up the Github repo for the gem in question, providing the command required to install it.

After running said command and installing the missing dependency jekyll serve is able to run as expected with the theme.

If the Demo Doesn't Load

If you go to the provided URL and don't see the site, like this for example:

...check on the value of baseurl in the _config.yml file. This file, which we'll talk more about later, controls the overall configuration for the entire site.

The baseurl variable is appended to the main domain, which when we work offline is http://localhost:4000.

In the above example we want our site to show up at http://localhost:4000. In the _config.yml file our baseurl variable is set to:

baseurl: "http://localhost"

This may seem right at first, but because this value is appended to the main domain it actually makes the site try to load at http://localhost:4000http://localhost.

So, we need to change the value to an empty string like this:

baseurl: ""

Your site will then load as expected.

If you want to load your site from a subdirectory instead, change the baseurl value to the name of the subdirectory, being sure to start and finish with a forward slash:

baseurl: "/themedemo/"

Familiarizing Yourself With the Theme

One of the main reasons it's a good idea to start by serving the theme straight out of its existing structure is, (other than checking it runs as expected), it gives you an opportunity to familiarize yourself with the theme's features and workflows.

Because Jekyll provides quite a lot of flexibility, its themes can offer functionality that's quite different from one to the next. After serving a demo of a new theme take a moment to browse around and see what type of structure the theme has. Look for things like whether the theme has category pages, featured images, author pages and so on. Take note of these features so you can the search the theme's documentation and learn to use them.

You should also look through the file and folder structure of the theme. The main areas you'll want to investigate are:

Any custom page layouts the theme may have in the _layouts folder
Any custom variables you'll need to set in the front matter of your content.

You'll also need to find out what site wide configuration options you may have to set in the site's _config.yml file to use the theme's features, such as social media URLs, author information, nav links and so on.

Making it Yours

Now you've had a chance to look over the theme and familiarize yourself, it's time to use it on your own site. Leave the demo version you already created unchanged so you have it to compare your freshly built site against.

Clear Out Demo Content

Make a new folder on your computer and re-extract all the theme's files into it.

This time, go into the _posts folder and delete all the files in there so the demo posts are removed.

After that, delete any .md (markdown) files from the root folder so all the demo pages are gone too.

If you wish, you may also like to locate and delete any images used within demo content, such as post featured thumbnails, if you plan to replace them with your own. Whether demo content images are present can vary from theme to theme.

If your theme does have demo images you want to delete but you're not sure where they are, check the theme documentation as it should tell you. Otherwise, you may need to go through the code in the theme's templates and figure it out from there.

Setting Up Site Config

Next, you should open up the _config.yml file from the root folder and setup any site wide variables that are required by the theme. Some settings will generally be common to all _config.yml files, such as title, email, description and a few others. However some settings will be specific to the given theme.

Exactly what you need to do in the site config file depends on the specific theme, so it's a good idea to refer to the theme's documentation at this point for guidance on what each setting does.

For example, in the Writer theme it's possible to setup a custom navigation menu using the nav_list variable to define a list of menu items. Each one has a label, permalink and a class that will make a Font Awesome icon appear next to it.

In contrast, the Astro theme doesn't use the Writer specifcnav_item variable, but has its own custom variables to allow you to add links to your various social media accounts, as well as to activate Disqus comments and so on.

Work through the variables in your own theme's _config.yml file until you have them all set to your liking.

Note that if you make changes like this after first serving your new site usingjekyll serve, you'll need to stop the process withCTRL + C and restart it to see any subsequent changes take effect.

Setup Your Homepage (If Required)

Some themes will give you the option to choose from multiple layouts for your homepage and set controls effecting their display. If this is the case you will probably find the settings can be changed in the front matter of the index.html file from the root folder.

If multiple layouts are available it's likely you'll find you can choose a different one by modifying the value of the layout setting–you'll have to refer to the theme's documentation to see what possible values can be used.

While you're editing the file, see if there are other values that should be changed to effect content that will be displayed on the homepage. For example, in the Writer theme it is possible to set a custom title and description to appear on the homepage only, as well as a featured image.

Add Your Own Pages

If you want to add pages such as "About" or "Contact" now is the time. Add a .md (markdown) document to the root folder of the site for each page you want to setup.

Note: some themes are setup to have all pages placed into a subfolder, (typically named "pages"), instead of the root folder so check on the theme docs to see if this is the case.

For example, here I've added an "About the Site" page (about.md), an "About Me" author profile page (author-kezz.md), and a "Contact" page (contact.md).

As you add page files you'll want to know if there are specific layout templates and/or front matter settings you should use with them. To find out you can refer to the theme's docs, or just copy and paste markdown files from the demo installation you did of the theme and rework them.

For example, here I have copied over an existing author page from the Writer demo and converted it into my own by renaming it then editing its front matter and content.

Adding Posts

Now that you have the essentials of your site structure setup it's time to add some posts. I recommend copying a post from the _posts folder in your demo site and pasting it into the installation you're working on. Then you can rename it with the date and the permalink you want for your new article. By reusing a demo post all the required front matter will be in place and you need only update it.

Categories, Tags and Other Extras

Some themes offer support for category and tag pages. This is not always the case though, and as such the implementation can differ from theme to theme. Check your theme's docs on what you might need to do to work with categories and tags on your site.

For example, in the Writer theme, for each category you want to use it is necessary to manually setup a folder and template file in a site subfolder named "category".

There may also be any number of other extra features the specific theme you are using has available. Be sure to have a good read through your theme's feature list and documentation to make sure you're across everything it includes.

Switching Themes on an Existing Site

If you already have a Jekyll site and just want to apply a new theme you'll want to go through almost the same process as we did above. The difference will come after deleting the demo content, when instead of adding fresh pages and posts you can just copy over your existing site's content.

If you have an existing Jekyll site with pages already present, copy and paste the associated markdown files from your old site in to your new one. Go through each page and update the front matter to use the new theme's layouts and required variables.

Then copy all your post files from your old _posts folder into your new one. It's going to be a little tedious, but you'll most likely have to go through each post file one by one and update its front matter with any settings that are required by the new theme, and delete any that were needed by the old theme but are no longer used.

If you have a folder with images and other media used in pages and posts on your old site, copy over the entire folder into your new site structure. Your posts and pages should still reference the same image locations, enabling them to continue to appear in your content.

Wrapping Up

So those are the essentials of how you setup a Jekyll theme! The finer points of the process will vary from theme to theme, but you can still follow these essential stages in each case. Let's quickly recap what those stages are.

Quick demo a new theme by extracting it and running: jekyll serve
Install any missing dependencies preventing the theme from being served.
Browse the front end of the demo site and note down features you need to learn to use.
Browse the file structure, in particular the_layouts folder, to see what custom layouts and variables you might need to use.
Create a second install of the theme and clear out the demo content pages, posts, and (optionally) images.
Fill in the settings in_config.yml to suit your site.
Setup the homepage (if required) by editing front matter variables in theindex.htmlfile in the root folder.
Create page markdown files with the required front matter, (or copy and paste them from your demo site / existing site).
Create post markdown files in the_posts folder with the required front matter, (or copy and paste them from your demo site / existing site).
Perform whatever extra setup the theme needs, such as creating category templates for example.

I hope this tutorial has helped you feel confident to tackle setting up a new Jekyll site with a custom theme, or switching your existing site's theme over to a new one.

For a thorough guide on using Jekyll, check out this course by Guy Routledge:

Thanks for reading and I'll see you again soon!

Kezz Bracey

Hi there. I'm a designer & coder who works in the areas of web design / development, game development and digital art. In the web space I'm a front end all rounder but I have a particular specialization in theme creation, no matter the platform. I also love finding the latest most efficient, user focused design and dev techniques of the day. In game development I'm addicted to playing with every different engine, toolset and framework I can find. In digital art I love everything from painting to vector work to pixel art to 3D modelling. In short, if it's creative and you can make it digitally, I love it.