Jekyll is a static website generation framework that allows you to take plain text files and convert them to a sophisticated blog without thinking about the databases, security problems, changes and other complexities that can come with other CMSs and blogging platforms as well.

Jekyll Theme Setup

As with other site management systems, Jekyll sites can use themes. However, Jekyll is not currently using themes in exactly the way you might be used to. At the moment Jekyll themes aren’t self-contained packages that need to be installed through an installer. When you download a Jekyll theme you will download all the files needed to run a whole Jekyll site as well.

In a future version of Jekyll, this might be improve, but for now, you’ll need to learn how to manage the fact that Jekyll themes come with a whole site attached to them.

In this tutorial, we’ll go through setting up a Jekyll theme right from the start.

Let’s start!

Installing Jekyll Static Site Generator

We’ll concentrate on the portion of your Jekyll site setup phase that occurs offline on your computer.


Working with Jekyll involves some use of the command line, but if you never worked with the command line before letting that put you off.

Jekyll can be use any operative system like Windows, Mac Os, Linux etc. There have different installation process for each of the operating system.

If you want to run using Jekyll on Windows, search the Jekyll installation for windows.

If you’re on Mac OS X, Linux, or Unix, you’ll need to ensure you’ve installed these prerequisites:

  1. Ruby (Macs Pre-installed)
  2. Ruby Gems (for managing Ruby packages)

To verify if you have Ruby installed to run the ruby -v command. To check Ruby Gems, execute gem -v These commands check for a version number in both cases so as long as you see a number returned in your terminal you are good to go.

We will work with Jekyll 4.x.x

Running Jekyll Installation

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

If you see a message stating you have no write permissions, preface the Sudo command and enter your password when prompted. Example : sudo gem install jekyll

You will then see printing out a few lines in the terminal that show the installation process being run. You’re finished when it says, “xx gem installed“.

Create a Default Jekyll Site

Let’s create a Jekyll site quickly, so you can see what it looks like in its default get acquainted with its file and folder structure. To produce the site, create a folder, then open a terminal pointing to the folder and run Jekyll new. Run the following command for that :

  • Step 1 : To create folder : mkdir foldername
  • Step 2 : Open folder via terminal : cd foldername
  • Step 3. Run the command : jekell new

Note: If you want to build a new Jekyll site in  subfolder, use the command: jekyll new subfolder_name instead

You will see a message in your terminal saying, New Jekyll site installed , when the site setup is complete. At this point, you can see the typical content of a Jekyll site inside your tab.

Now run the command jekyll serve to get your website offline activated.

If you see the message “Server running… press ctrl-c to stop“, go to the http://localhost:4000 address in your browser, and check the default Jekyll site.

Now that you’ve seen what a default Jekyll site’s file and folder layout looks like, as well as its default themed state, you’ll get a better understanding of what you’re seeing inside.

Install new jekyll themes

As you know from what we’ve talked about so far in this tutorial, Jekyll themes now come with all the files required to run a whole site. And as you’ve seen in the last section, once you’ve got all those files you can run jekyll serve to allow user viewing of that site.

That means you can just extract it when downloading a new Jekyll themes, run jekyll serve and demoing the theme right away on a fully functional Jekyll site. Many themes are also to come with already included demo material.

Let’s look at some examples using the Tfolio and Doxy themes, (or whatever you like).

Once extracted, search through the structure of the theme until you find the root folder which gives all the Jekyll site files. Earlier this folder should be recognizable from your default Jekyll installation. Look for stuff like the file _config.yml, the _includes directory etc.

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

If everything is successful you will see the message “Server Address:” with a URL to the end of the terminal displayed. Copy and paste this URL into your browser and see a preview of your new theme.

Missing dependency?

In some cases, when you try running jekyll serve, you might see an error message. If this happens, look to see if the message complains about a missing dependency, that is, something is missing from your setup that the theme needs to function.

In this case, in the red error text you can see that the gem “jekyll-paginate” is missing:

So if you run bundle install , it will install automtically the necessary packages, gems what required for the jekyll theme.

If the demo doesn’t load

If you are going to the provided URL and don’t see the site, check the base- URL value in the file _config.yml. This file, which we will address in more depth later, controls the overall site configuration. The base-URL variable is connected to the main domain which is http://localhost:4000  while we’re operating offline.

Here, we want our website to appear at . In the file _config.yml our variable URL is set to:

url: “

It may seem correct at first, but because this attribute is applied to the main domain, the platform attempts to load it. If you want custom baseurl  example : You should add baseurl “blog” for that

So, we must change the value to an empty string, such as:

baseurl: “” to baseurl “/blog”

Then your site will load as you would want.

Getting familiar with the Jekyll Themes

Since Jekyll provides a lot of versatility, its themes can provide features that are very different from one to the next. Take a moment to browse around after serving a demo of a new theme and see what kind of structure the theme has. Look for items like if the theme has pages of categories, photos featured, pages of writers etc. Take note of these features so you can search and learn how to use the documentation for the theme.

Claiming it for yourself

Now you’ve had a chance to look over the theme and get acquainted with it, it’s time to use it on your site. Keep the demo version you’ve developed unchanged and you’ve got it to compare your newly designed website too.

Clear out demo content

Make a new folder on your computer and re-extract files from all the theme in it. This time, go to the _posts folder and delete all the files in there to remove the demo posts.

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

If you wish, you might also like to find and remove images that are used inside demo content, such as thumbnails featured in the post, if you intend to replace them with your own. Whether photos of the demo content are present may differ from topic to topic.

Setting Up Site Config

Next, open the _config.yml file from the root folder, and set up any site-wide variables that the theme requires. In general, certain settings would be common to all _config.yml files, such as title, email, definition and a few more. Some settings will, however, be specific to the theme given.

Note that if you make such changes after you first use Jekyll serve to serve your new site, you will need to stop the process with CTRL+C and restart it to see any subsequent changes take effect.

Setting up the homepage

Some themes will give you the option of choosing your homepage from multiple layouts and setting controls to affect their display. If this is the case, you will probably find that the settings from the root folder can be changed in the front of index.html file.

If several templates are open, you can find that by changing the value of the layout setting you can select a different one – you will have to refer to the documentation of the style to see what potential values can be used.

Add your pages

Now is the time to add pages like “About” or “Contact“. For each page you wish to set up, add a .md (markdown) document to the site’s root folder.

Note: some themes are designed to put all the pages in a subfolder (typically called “pages“) instead of the root folder, so check the theme documentation to see if this is the case. Best SEO practice to keep the pages in root folder.

You’ll want to know if there are specific layout templates and/or front-matter settings that you should use with them when you add page files. To find out, you should link to the docs of the project, or just copy and paste markdown files from the demo installation and rework them from the project you did.

Adding posts

Now that you have the essential elements of setting up your site structure it’s time to add some posts. I recommend that you copy a post from your demo site’s _posts folder and paste it into the installation where you are working. Then you can rename it with the date you want for your new post, and the permalink. All the appropriate front matter will be in place by reusing a demo article, and you just need to update it.

Categories, Texts and Other Extras

Some themes offer category and tag support pages. Nonetheless, this is not always the case, and as such the implementation may vary from subject to the theme. Check the docs on your theme about what you may need to do to work with your site’s categories and tags.

The specific theme that you are using may also have any number of other additional features available. Make sure you have a thorough read through the feature list and details of your theme to make sure you are following what it contains.

Switching Jekyll Themes on an Existing Site

If you already have an existing Jekyll site with pages, copy and paste the corresponding markdown files from your old site into your new one. Go through each page and update the front-end to use the templates and necessary variables of the new theme.

Then copy all your post files to your new folder from your old _posts folder. It’s going to be a little repetitive, but you’re most likely going to have to go through will post file one by one and update its front matter with any settings that the new theme needs, and delete any that the old theme required but no longer uses.

Final Point

And those are the basics of how to set up a Jekyll theme! The process’s basic tenets can vary from theme to theme, but in each case, you can always follow the basic stages. 

I hope that this tutorial has helped you feel confident about setting up a new Jekyll site with a custom theme or changing the theme of your existing site to a new one. For having latest Jekyll themes browse here!

Leave a Comment

No Comment