Written by: Geoffrey Callaghan

how to create a jekyll theme

How To Create A Jekyll Theme

Creating a Jekyll theme involves several steps, from setting up a Jekyll environment to designing and coding the theme, and finally packaging it for reuse. Here’s a step-by-step guide to help you create a Jekyll theme:


  • Basic knowledge of HTML, CSS, and Liquid (Jekyll’s templating language).
  • A development environment with Ruby and Jekyll installed.

Step 1: Setting Up Your Environment

  1. Install Ruby and Jekyll: If you haven’t already, install Ruby and Jekyll. You can follow the instructions on the Jekyll installation page.

    gem install jekyll bundler
  2. Create a New Jekyll Site:

    jekyll new my-theme
    cd my-theme
  3. Start the Jekyll Server:

    bundle exec jekyll serve

    Open your browser and navigate to http://localhost:4000 to see your new Jekyll site.

Step 2: Structure Your Theme

  1. Directory Structure: Organize your theme with the following structure:

    ├── _includes/
    ├── _layouts/
    ├── _sass/
    ├── assets/
    │   ├── css/
    │   ├── images/
    │   └── js/
    ├── _config.yml
    ├── index.html
    ├── LICENSE.txt
    └── README.md
  2. Create Layouts: In _layouts/, create a default layout file:

    <!-- _layouts/default.html -->
    <!DOCTYPE html>
    <html lang="en">
      <meta charset="UTF-8">
      <title>{{ page.title }}</title>
      <link rel="stylesheet" href="{{ '/assets/css/styles.css' | relative_url }}">
      {% include header.html %}
      {{ content }}
      {% include footer.html %}
  3. Create Includes: Add reusable components like header and footer in the _includes/ directory:

    <!-- _includes/header.html -->
      <h1>{{ site.title }}</h1>
          <li><a href="{{ '/' | relative_url }}">Home</a></li>
          <!-- Add more navigation links here -->
    <!-- _includes/footer.html -->
      <p>&copy; {{ site.time | date: '%Y' }} {{ site.title }}</p>

Step 3: Add Styling and Scripts

  1. Sass Files: In _sass/, create partials for styles. For example:

    // _sass/_variables.scss
    $primary-color: #333;
    // _sass/_base.scss
    body {
      font-family: Arial, sans-serif;
      color: $primary-color;
  2. Main Stylesheet: Create a main stylesheet in assets/css/ that imports these partials:

    // assets/css/styles.scss
    @import "variables";
    @import "base";
  3. JavaScript Files: Place your JavaScript files in assets/js/.

Step 4: Configure Your Theme

  1. _config.yml: Update your site configuration:

    title: My Jekyll Theme
    description: A custom Jekyll theme
  2. Gemfile: Add theme dependencies (if any):

    gem "jekyll-theme-my-theme", path: "."

Step 5: Package Your Theme

  1. Convert Site to Theme: Modify your theme to follow Jekyll theme guidelines:

    # _config.yml
    theme: "jekyll-theme-my-theme"
  2. Theme Gem Specification: Create a my-theme.gemspec file:

    Gem::Specification.new do |spec|
      spec.name          = "jekyll-theme-my-theme"
      spec.version       = "0.1.0"
      spec.summary       = "A custom Jekyll theme"
      spec.license       = "MIT"
      spec.files         = Dir.glob("**/*").reject { |f| f.include?("vendor/") || f.include?("node_modules/") }
      spec.add_runtime_dependency "jekyll", "~> 4.0"
  3. Build and Install the Theme: Build the gem and install it locally:

    gem build my-theme.gemspec
    gem install jekyll-theme-my-theme-0.1.0.gem

Step 6: Share Your Theme

  1. Publish to GitHub: Push your theme to a GitHub repository.

  2. Release on RubyGems: To make your theme available to others, you can publish it to RubyGems. Follow the RubyGems guidelines for publishing a gem.

Final Steps

  1. Test Your Theme: Create a new Jekyll site and apply your theme to ensure it works correctly.

  2. Document Your Theme: Provide clear documentation on how to use and customize your theme in the README.md.

By following these steps, you can create a Jekyll theme from scratch, package it, and share it with others.