Jekyll Theme Setup Tutorial: Complete Walkthrough (2026)

This tutorial walks you through the complete process of setting up a Jekyll theme — from a blank machine to a fully configured, live website. No prior Jekyll experience needed.

What You Will Need

A computer running macOS, Windows, or Linux
A GitHub account (free)
Basic comfort with the terminal/command prompt
About 30 minutes

Part 1: Install Jekyll

Jekyll runs on Ruby. Install it first.

macOS

Apple ships an old version of Ruby — use rbenv for a proper install:

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install rbenv and Ruby
brew install rbenv ruby-build
rbenv install 3.2.0
rbenv global 3.2.0

# Add rbenv to your shell
echo 'eval "$(rbenv init -)"' >> ~/.zshrc
source ~/.zshrc

# Install Jekyll
gem install jekyll bundler

Windows

Download RubyInstaller (Ruby+Devkit version)
Run the installer and follow the prompts
Open a new command prompt and run:

gem install jekyll bundler

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install ruby-full build-essential zlib1g-dev

echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

gem install jekyll bundler

Verify your install:

jekyll -v
ruby -v

For detailed platform-specific instructions, see the official Jekyll installation guide.

Part 2: Choose a Jekyll Theme

Before creating your site, pick a theme that matches your goals. Browse JekyllHub’s full theme collection or use these quick picks:

Use Case	Theme	Stars
Tech / developer blog	Chirpy	7,000+
Personal blog / portfolio	Hydejack	8,000+
All-purpose blog	Minimal Mistakes	12,000+
Academic / research	al-folio	10,000+
Documentation	Just the Docs	7,000+
Beginner-friendly	Jekyll Now	8,400+

Part 3: Set Up Your Site

There are two main approaches depending on the theme you chose.

Approach A: Gem-based themes (Minimal Mistakes, etc.)

# Create a new Jekyll site
jekyll new my-site
cd my-site

Open Gemfile and replace the default theme:

# Remove this line:
# gem "minima"

# Add your theme:
gem "minimal-mistakes-jekyll"

Open _config.yml and set the theme:

theme: minimal-mistakes-jekyll

Install and run:

bundle install
bundle exec jekyll serve

Approach B: Fork-based themes (Chirpy, al-folio, etc.)

Most modern themes recommend starting from their template:

# Example: Chirpy
git clone https://github.com/cotes2020/chirpy-starter my-site
cd my-site
bundle install
bundle exec jekyll serve

Visit http://localhost:4000 to preview your site.

Part 4: Configure Your Site

Open _config.yml — this is the control centre for your Jekyll site. Update these essential fields:

# Site identity
title: "Your Site Name"
tagline: "A short description"
description: >-
  A longer description of your site used in meta tags and search results.
  Keep it between 120–160 characters.

# Your URL (critical for SEO and social sharing)
url: "https://yourusername.github.io"
baseurl: ""

# Author information
author:
  name: "Your Name"
  email: "you@example.com"
  bio: "A short bio"
  avatar: "/assets/images/avatar.jpg"

# Social profiles
github_username: yourusername
twitter_username: yourusername
linkedin_username: yourusername

# Timezone and language
timezone: America/New_York
lang: en

# Build settings
permalink: /:year/:month/:day/:title/
paginate: 10

# Plugins
plugins:
  - jekyll-feed
  - jekyll-sitemap
  - jekyll-seo-tag

SEO tip: The url field must be set correctly for jekyll-seo-tag to generate proper canonical URLs and Open Graph tags. Never leave it as http://localhost:4000 in production.

Part 5: Customise the Look

Change colours

Most themes expose SCSS variables. Create assets/css/main.scss:

---
---

// Override variables before importing the theme
$primary-color: #2563eb;
$link-color: #2563eb;
$background-color: #ffffff;

@import "your-theme-name";

Override a layout

# Find where the theme gem is installed
bundle info --path your-theme-gem

# Copy the layout you want to change
cp /path/to/theme/_layouts/post.html _layouts/post.html

# Edit your local copy freely

Part 6: Add Your First Post

Create a file in _posts/ named YYYY-MM-DD-your-title.md:

---
title: "My First Post"
date: 2026-06-10 10:00:00 +0000
categories: [Blog]
tags: [jekyll, first-post]
description: "A brief description for SEO and social sharing"
---

This is my first Jekyll post. Write your content here in Markdown.

## A Section Heading

Your content goes here.

```code
echo "Code blocks work too"

Jekyll renders this into HTML automatically when you save.

---

## Part 7: Deploy to GitHub Pages

### Step 1: Create a GitHub repository

Go to [github.com/new](https://github.com/new).

- Name it `yourusername.github.io` for a personal site
- Leave it public
- Do not add a README (you already have files)

### Step 2: Push your site

```bash
git init
git add .
git commit -m "Initial site setup with Jekyll theme"
git branch -M main
git remote add origin https://github.com/yourusername/yourusername.github.io.git
git push -u origin main

Step 3: Enable GitHub Pages

In your repository, go to Settings → Pages:

Source: Deploy from a branch
Branch: main / root
Click Save

Your site goes live at https://yourusername.github.io within 2 minutes.

Part 8: Verify Everything Works

After deployment, check:

Site loads at https://yourusername.github.io
Posts appear on the homepage
Images load correctly
Navigation links work
Site looks correct on mobile (use browser DevTools)
View source and confirm <meta name="description"> is populated

Submit to Google Search Console

https://yourusername.github.io/sitemap.xml

This tells Google your site exists and accelerates indexing.

Troubleshooting Common Setup Issues

Problem	Solution
`Liquid Exception` on build	Check front matter YAML syntax — indentation must be consistent
CSS not loading	Verify `baseurl` in `_config.yml` matches your repository setup
Theme not applying	Run `bundle update` and restart `jekyll serve`
Posts not showing	Confirm filename format: `YYYY-MM-DD-title.md` and date is not in the future
Build fails on GitHub Pages	Check the Actions tab — the error message shows exactly what failed

What to Do Next

Your site is live. Here is what experienced Jekyll users do next:

Write 3–5 posts before promoting — gives visitors something to read
Add a custom domain — set up in GitHub Pages settings and your DNS provider
Enable comments — Giscus uses GitHub Discussions for free
Set up Google Analytics — add your measurement ID to _config.yml
Check your Lighthouse score — run Chrome DevTools → Lighthouse for a performance and SEO audit

Browse More Jekyll Themes

Not happy with your current theme? Browse 70+ Jekyll themes on JekyllHub — with real screenshots, live demos, and GitHub star counts to help you find the perfect fit.

References

jekyll theme setup jekyll tutorial jekyll configuration github pages