How to Customize a Jekyll Theme (Complete Guide 2026)

Customizing a Jekyll theme doesn’t mean editing the theme files directly — that approach breaks every time you update the theme. The right way is to use Jekyll’s override system: copy only the files you want to change into your project, and Jekyll will use your version instead.

This guide covers everything from changing colours to overriding layouts to adding completely new features.

How Jekyll Theme Overrides Work

Jekyll loads files in this priority order:

Your project files (highest priority)
Theme gem files
Jekyll defaults

This means if you create _layouts/post.html in your project, Jekyll uses it instead of the theme’s version — without touching the original.

1. Change Colours and Fonts (SCSS Override)

Most modern themes expose SCSS variables you can override. Here is the standard approach:

Step 1: Find the theme’s variable file

bundle info --path minimal-mistakes-jekyll

This shows the gem path. Look for _sass/minimal-mistakes/_variables.scss.

Step 2: Create your override file

Create assets/css/main.scss in your project:

---
---

// Override theme variables BEFORE importing the theme
$primary-color: #2563eb;
$font-family-sans-serif: "Inter", sans-serif;
$border-radius: 8px;

// Then import the theme
@import "minimal-mistakes";

Step 3: Rebuild

bundle exec jekyll serve

Your colour and font changes apply site-wide instantly.

2. Override a Layout

To modify a theme’s layout without editing the gem:

Step 1: Copy the layout file

cp $(bundle info --path minimal-mistakes-jekyll)/_layouts/post.html _layouts/post.html

Step 2: Edit your local copy

Open _layouts/post.html and make your changes. Jekyll will use this file automatically.

3. Override an Include

Includes work the same way as layouts:

cp $(bundle info --path your-theme)/_includes/header.html _includes/header.html

Edit _includes/header.html freely — your version takes precedence.

4. Customize `_config.yml`

Most themes expose configuration options in _config.yml. This is the safest place to make changes since it never conflicts with theme updates:

# Minimal Mistakes example
minimal_mistakes_skin: "dark"
author:
  name: "Your Name"
  bio: "Your bio here"
  avatar: "/assets/images/avatar.jpg"

# Typography
title_separator: "—"
words_per_minute: 200

Consult your theme’s documentation for available options.

5. Add Custom CSS Without Overriding SCSS

For small tweaks, create a custom CSS file and include it in your layout:

/* assets/css/custom.css */
.site-header {
  border-bottom: 2px solid #2563eb;
}

.post-title {
  font-size: 2.5rem;
}

Then reference it in your _includes/head.html override:

<link rel="stylesheet" href="/assets/css/custom.css">

6. Add Google Fonts

Override _includes/head.html and add:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;700&display=swap" rel="stylesheet">

Then set the font in your SCSS override:

$font-family-sans-serif: "Inter", system-ui, sans-serif;

Most themes read navigation from _data/navigation.yml:

main:
  - title: "Blog"
    url: /blog/
  - title: "Themes"
    url: /themes/
  - title: "About"
    url: /about/

8. Modify the Home Page

To customise the homepage, create index.html or index.md in your project root. Most themes support front matter options to configure sections:

---
layout: home
hero_title: "My Jekyll Site"
hero_subtitle: "Writing about code and design"
show_posts: true
posts_limit: 6
---

Best Practices for Customizing Jekyll Themes

Never edit gem files directly — changes are lost on bundle update
Override only what you need — fewer overrides = easier theme updates
Use _config.yml options first — most themes expose more than you expect
Keep a _sass/custom.scss — a single file for all your tweaks is easier to maintain
Test with bundle exec jekyll serve --livereload — see changes instantly

Popular Themes and Their Customization Docs

Theme	Customization Guide
Minimal Mistakes	Docs
Chirpy	Docs
Just the Docs	Docs
Hydejack	Docs

References

customize jekyll theme jekyll scss jekyll layouts tutorial