How to Create a Material Design Jekyll Theme


In my opinion, Jekyll has the potential to become as popular as WordPress. The only thing holding it back is the fact that there aren’t enough themes for it. Indeed, you can count the good ones on your finger tips. Thankfully, creating themes for Jekyll is extremely easy. If you are comfortable with HTML, and are familiar with a good CSS framework, it won’t take you very long either. In this tutorial, I’m going to show you how to create a responsive, material design Jekyll theme from scratch. We’ll be using Materialize as the CSS framework. This will be a theme you can immediately start using for a blog. And, with a little more polish and customizations, you can even aspire to sell it!


In order to follow this tutorial, you must obviously have Jekyll installed and configured on your computer. You must also have a basic understanding of HTML and CSS.

Create a New Jekyll Theme

To create a new Jekyll theme, you must use the new-theme command of Jekyll’s CLI.

jekyll new-theme my-material-theme

You will now have a new directory called my-material-theme. All your theme’s files will be inside this directory. Enter it using cd.

Create Includes

Ideally, your theme must have includes for a header and a footer. They are not always necessary, but, by having them, you can make your theme more flexible. Let’s create the header first by creating a new file called header.html inside the _includes directory. Open it using any code editor. I prefer Brackets.

The header must contain the doctype, <html>, and <head> tags. Inside the <head> tag, you must add all your CSS requirements, and <meta> tags. Accordingly, add the following code to the file:

<!DOCTYPE html>
      <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      <link rel="stylesheet" href="">

As you can see, I’m using a CDN to load the CSS of the Materialize framework. Note that I’ve opened <body> tag and not closed it. You’ll see why next.

Create a new file called footer.html inside the _includes directory. The footer must contain all your <script> tags, and the closing tags for both <body> and <html>.

<script src=""></script>

I’ve, of course, used a CDN again to load the JS file of the Materialize framework.

Create a Default Layout

Now that we’ve created a header and footer, we must create the layout that goes between them. You are free to use any layout you want.

Go to the _layouts folder and open default.html. This file should already contain a content template. All you need to do is surround that with your layout. Here’s my layout, with a navbar, a simple container, and a footer:

{% include header.html %}

    <div class="nav-wrapper">
      <div class="container">
          <a href="#" class="brand-logo"> {{ site.title }} </a>      

<div class="container">
     {{ content }} 

<footer class="page-footer">
  <div class="container">
    <div class="row">
      <div class="col l6 s12">
        <h5 class="white-text"> {{ site.title }} </h5>
        <p class="grey-text text-lighten-4"> {{ site.description }} </p>
      <div class="col l4 offset-l2 s12">
        <h5 class="white-text">Links</h5>
          <li><a class="grey-text text-lighten-3" href="#!">Link 1</a></li>
          <li><a class="grey-text text-lighten-3" href="#!">Link 2</a></li>
  <div class="footer-copyright">
    <div class="container">
    © 2014 Copyright {{ }} | All rights reserved.

{% include footer.html %}

Create the Home Page

Well, every website has a home page, usually called index.html. Therefore, create the file at the root of your theme, and open it. Inside it, add YAML front-matter saying it uses the default layout.

The home page usually lists all the posts present the blog. Therefore, we must now create a for loop that loops through the site.posts array. Inside the loop, you must specify how each post must be rendered. The following code creates a material card for each post:

layout: default
{% for post in site.posts %}
<div class="row">
    <div class="col s12 m6">
      <div class="card">
        <div class="card-content">
          <span class="card-title">{{ post.title }}</span>
          <p>{{ post.excerpt }}</p>
        <div class="card-action">
          <a href="{{ post.url | prepend: site.baseurl }}">
            Read More
{% endfor %}

The theme is now ready!

Here’s a sample blog using the theme:

material design jekyll theme

Generate a Gem

Optionally, if you want to publish your theme, you can convert it into a gem so that others can use it more easily. You can do so by running the following command:

gem build my-material-theme.gemspec

Note, however, that index.html won’t be a part of the theme gem. To solve this problem, you can move all the contents of index.html to a new type of layout inside the _layout directory.


You now know how to create a theme for Jekyll from scratch. As you saw, it’s very easy and takes very little time(unless you have a complicated design).

If you found this article useful, please share it with your friends and colleagues!