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

Understanding what you built

It is worth pausing to understand what Jekyll actually produced during your setup. When you run bundle exec jekyll build, Jekyll reads every Markdown file in _posts/ and _pages/, processes their Liquid templates using the variables defined in _config.yml and each file’s front matter, and writes a complete HTML file for each page to the _site/ directory.

The _site/ folder is the complete, self-contained website. Every file in it is plain HTML, CSS, and JavaScript — no PHP, no database, no server-side processing needed. When you push to GitHub Pages, GitHub serves files directly from the equivalent of _site/. When a visitor loads your homepage, they get a pre-built HTML file delivered directly from GitHub’s CDN — not a server generating a page on demand.

This architecture is why Jekyll sites are fast, reliable, and cheap to host. There is no application server to crash, no database to corrupt, no plugin vulnerability to patch. The attack surface is as minimal as a website can be. The hosting cost on GitHub Pages is zero. The page load time is as fast as a CDN can deliver a static file.

Making your workflow sustainable

A common mistake after the initial setup is treating the site as a project to “finish” rather than a platform to maintain. Jekyll sites that stay current require only one sustainable habit: writing and publishing regularly.

The minimal maintenance workflow: once a month, run bundle update to keep gems current, check for any GitHub Pages build failures in the Actions tab, and review whether any posts need updates based on changes in the topics you write about. This takes twenty minutes and keeps the site current indefinitely.

For content, the most sustainable publishing cadence is whatever you can maintain without strain. One post per month for a year produces twelve posts. Twelve posts on a focused topic, each genuinely answering a specific question your target readers have, is more than enough to establish a credible presence and start attracting search traffic. Quality and consistency over a moderate period dramatically outperforms a burst of posts followed by silence.

The toolchain is stable: Jekyll 4.x, Ruby, Bundler, and GitHub Pages have been reliable for years and show no signs of instability. The themes you install today will continue working with modest maintenance. The Markdown files you write are human-readable plain text files that will be accessible regardless of what happens to any particular tool or service. This durability is one of Jekyll’s underappreciated advantages over database-backed CMS platforms — your content investment is genuinely portable and long-lasting.

Choosing the right theme for the long term

The theme you installed for this tutorial may not be the theme you use in two years. That is fine — changing a Jekyll theme is straightforward because your content (the Markdown files) is completely decoupled from the presentation layer. When you find a theme that better fits how your site has evolved, migration is primarily a configuration task rather than a content rewrite.

When evaluating themes for the long term, prioritise maintainability over visual novelty. A theme that is actively maintained by a committed developer or organisation is far more valuable than a visually impressive theme that has not been updated in two years. Check the GitHub repository’s commit history, the response rate on open issues, and whether the maintainer has documented upgrade paths between versions.

The best Jekyll themes to stake a long-term site on include Minimal Mistakes (maintained since 2013 with an extraordinary track record), Chirpy (active development, responsive maintainer, growing community), and Just the Docs (backed by the same organisation that develops it for their own documentation needs). All three will be here in five years. Browse the complete list at JekyllHub with filtering by maintenance status to find the right theme for your specific use case and commitment level.

Customising your theme systematically

After installation, resist the urge to change everything at once. Work through customisations in a deliberate order: start with _config.yml settings like your site title, description, and social links — most themes read these directly. Next, set colours by editing SCSS variables if the theme exposes them. Only after these non-destructive changes should you start overriding actual layout files.

This order matters because _config.yml changes affect every page and the theme handles them entirely, so you cannot break anything. Variable changes affect only style — easy to revert. Layout overrides require understanding what the original file was doing, so they carry more risk and benefit from being saved until you understand the theme well.

Keep a clean working branch in git. Commit your base installation before any customisation, so you always have a known-good state to roll back to. Commit each meaningful group of customisations separately — “Update colours and fonts,” “Add logo,” “Override post layout” — so your git history documents what you changed and why. This discipline becomes invaluable if a Jekyll update later changes how the theme renders and you need to trace what overrides might be causing conflicts.

Many themes provide a _config.yml with every available option listed and commented out. Reading this file end-to-end before touching layout files reveals options you did not know existed and often eliminates the need to override a layout at all. A thorough read of the theme documentation, including the configuration reference, is time well spent before writing a single line of custom HTML or SCSS. Build incrementally, commit often, and enjoy the process.

jekyll theme setup jekyll tutorial jekyll configuration github pages