A Live Developer Journal

Create A Skeleton Jekyll Theme


It's pretty easy to get started with creating a Jekyll Theme, because Jekyll lets you generate a bare-bones theme directory.

When you run the jekyll new-theme command, you'll get a folder called your-theme-name which has the following directory structure:

|-- Gemfile
|-- LICENSE.txt
|-- README.md
|-- _includes
|-- _layouts/
|   |-- default.html
|   |-- page.html
|   |-- post.html
|-- sass/
|-- assets/
|-- your-theme-name.gemspec

Tip: Run tree in the command-line to generate a directory structure tree like the one above.

This directory structure is literally the bare bones of a Jekyll site. Most of the folders don't have anything in them, they're just there to help you organize your files

Commit your skeleton theme so far

Before going any further, commit these files to a repository for your theme. That way, you know that any changes you make after this commit are your own. Here are the steps for doing this:

remote add origin git@gitlab.com:UserName/your-theme-name.git git config --get remote.origin.url 🎉 Start Live developer Journal jekyll theme.

Commit message tips:

Further Setup

There are couple more things I like to set up before moving forward. Like changing the license if needed, adding a decent HTML boilerplate to the default layout, setting up my assets and sass folder to match my own organizational preferences.

Below is a set of brief explanations and suggestions for each of the files/folders in our auto-generated theme.

Gemfile and Gemfile.lock

A Gemfile describes the gem dependencies required to execute associated Ruby code (source: Bundler Gemfile docs)

A Gemfile.lock file is used for recording the exact versions of the gems you installed when installing them. When you run `bundle install` to install Gems, bundler first looks inside the Gemfile.lock to install the version captured there before it looks in the Gemfile. This stops bugs happening where a project on one computer may install a version that is different to the one that was intended.

We don't need to make any changes to these at the moment.


The default license file generated is the MIT license, which lets anyone use, modify, distribute, sell, merge etc projects they make from your project.

It's up to you whether you want to use an alternative license.


The "includes" folder is used to store partial templates that you can include in any of your files. You might have an individual file for a header, footer, forms and general components.

Personally, I only add things here as an when needed. Every project is different.


The layouts folder contains three files. Each of them are templates that wrap around your content.


At the moment, the default layout contains the "content }}", which is a variable that represents the rendered content of the post or page being wrapped.

I like to add in a HTML boilerplate for every page, where the title is pulled from the page (`Create A Skeleton Jekyll Theme`), same with the description and keywords if you want.

This is also a good place to add analytics, rss or seo scripts if you want to.

post.html and page.html

The post layout is intended to be used for the articles you write in the posts directory. While the page layout is intended to be used for main site pages like about pages, contact etc.

Both of these layout templates inherit from the default layout because they contain the front matter:

layout: default

So whenever you want to use a page or post layout, set the layout to any of those and they'll automatically inherit the default layout.

It's up to you what default things you want for pages and posts. I like to include a heading with the page title for each of the posts so I don't have to do it manually on each page.

_sass/ and assetsl/

The sass folder is currently empty. So this is something worth setting up. Here's what I do:

@import "main";

Now, all of your sass partial files are imported into a main sass file, which is then imported into the main styles file. Under the surface, Jekyll converts "styles.scss" to "styles.css" when we build our site.

In our "layouts/default.html" file, add the link to your stylesheet:

The assets folder is used to store things like CSS, JS, images, documents etc. We already created the CSS folder. It's up to you if you want to create folders for the rest at this stage.


The site/ directory contains the generated files for our entire site. This folder is ignored in our ".gitignore" file. Don't change whats inside this.


The "*your-theme-name*.gemspec" file is the gem that is used to package up our theme for others to use once it's ready. We don't need to worry about it right now. Though I do like to update the following values:

spec.summary = "provide a short description of your theme"
spec.homepage = "link to theme repository or live demo"

Extra files/folders

Here are some extra things I think are important to add to the skeleton theme, that weren't included.


<h1>{{ page.title }}</h1>


I also don't want to have to specify that the layout is a post every time I write a new post. So I can make all posts inherit a post layout by default, by creating a "config.yml" file at my projects root with the following settings:

      path: "" # an empty string here means all files in the project
      type: "posts" # now we are getting all files in the _posts directory
      layout: "default"


Create an "index.html" page in your project's root, with the following markup that displays all posts in your "posts" directory.

layout: default

{% for post in site.posts %}
  <li><a href="{{ post.url }}">{{ post.title }}</a>
{% endfor %}


layout: default


<p>Page not found! :(</p>

That's it for now, woo woo! If you want to have a look at what this all looks like once it's done, here's the finished skeleton theme