Remote themes are one of the most convenient ways to use a Jekyll theme — especially on GitHub Pages. Instead of installing a theme as a Ruby gem, you reference it directly from its GitHub repository. The hosting platform (GitHub Pages, Netlify, Cloudflare Pages) fetches the theme files at build time and applies them to your site.

What is a remote theme?

A remote theme is a Jekyll theme hosted as a public GitHub repository that you can apply to your site without manually copying its files. You reference it with a single remote_theme setting in _config.yml.

This is different from installing a theme as a gem (gem "minima" in your Gemfile). With remote themes:

• You do not need to add a gem to your Gemfile for the theme
• The theme files are fetched from GitHub at each build
• You can use any version-compatible public Jekyll repository as a theme
• Updating the theme means changing one line in _config.yml

The jekyll-remote-theme plugin

Remote themes are powered by the jekyll-remote-theme plugin, maintained by GitHub. It is automatically enabled on GitHub Pages. For other platforms (Netlify, Cloudflare Pages, Vercel), you add it yourself.

Setting up on GitHub Pages

GitHub Pages has jekyll-remote-theme built in. Just add remote_theme to _config.yml:

remote_theme: mmistakes/minimal-mistakes

That is the complete setup. No Gemfile changes, no plugin installation.

Setting up on other platforms

Add the plugin to your Gemfile:

group :jekyll_plugins do
  gem "jekyll-remote-theme"
end

Add it to _config.yml:

plugins:
  - jekyll-remote-theme

remote_theme: mmistakes/minimal-mistakes

Run bundle install and commit Gemfile.lock.

Specifying a remote theme

The remote_theme value follows the format owner/repository:

# Use the latest commit on the default branch
remote_theme: mmistakes/minimal-mistakes

# Pin to a specific tag or release
remote_theme: mmistakes/minimal-mistakes@4.26.0

# Pin to a specific branch
remote_theme: mmistakes/minimal-mistakes@master

# Pin to a specific commit SHA (most stable)
remote_theme: mmistakes/minimal-mistakes@d9c6f33

Pinning to a version is strongly recommended for production sites. Without pinning, your site rebuilds with whatever is the latest commit on the theme’s default branch — a theme update could unexpectedly change your site’s appearance.

Popular themes available as remote themes

These themes are widely used and fully support remote_theme:

Customising a remote theme

The power of remote themes is that you can override any file from the theme without touching the theme’s repository. Jekyll’s file resolution works like this: your files take precedence over the theme’s files.

To override a theme file, create the same file in your project. Jekyll uses yours and ignores the theme’s version.

Overriding a layout

If the theme has _layouts/post.html and you want to customise it:

1. Copy the file from the theme’s GitHub repository
2. Place it at _layouts/post.html in your project
3. Modify it as needed

Your _layouts/post.html now overrides the theme’s.

Overriding an include

# Theme's version (not in your repo)
_includes/nav.html

# Your override (in your repo — takes precedence)
_includes/nav.html   ← your custom nav

Adding custom CSS

Most remote themes look for a assets/css/style.scss or similar entry point. Add your custom styles:

// assets/css/custom.scss
---
---

// Import the theme's base styles
@import "jekyll-theme-primer";

// Your overrides
.site-header {
  background: #1a1a2e;
}

.post-title {
  font-family: "Georgia", serif;
}

For Minimal Mistakes specifically, add to _config.yml:

# Minimal Mistakes custom CSS
head_scripts:
  - /assets/css/custom.css

Or create _sass/custom.scss and import it in the theme’s skin file.

Customising theme configuration

Remote themes typically expose configuration options via _config.yml. Check the theme’s documentation for available settings:

# Minimal Mistakes theme settings
minimal_mistakes_skin: "dark"   # or: air, aqua, contrast, default, dirt, neon, mint, plum, sunrise

# Site navigation
header_pages:
  - about.md
  - contact.md

# Author profile
author:
  name: Marcus Webb
  avatar: /assets/images/avatar.jpg
  bio: "Developer and technical writer."
  links:
    - label: GitHub
      icon: "fab fa-fw fa-github"
      url: "https://github.com/marcuswebb"

Remote themes vs gem-based themes vs downloaded themes

When to use a remote theme

• You want a well-maintained community theme without vendoring its files
• You are on GitHub Pages and the theme is not a whitelisted gem
• You want easy updates by changing a version pin in _config.yml

When to use a gem theme

• Your platform supports all gems (Netlify, Cloudflare Pages)
• The theme is distributed as a gem on RubyGems
• You want offline builds without fetching from GitHub

When to download and own the theme files

• You plan to heavily customise the theme beyond small overrides
• You want no external dependency at build time
• You bought a premium theme and have the source files

Building on top of a remote theme

Many sites use a remote theme as a foundation and add content on top:

my-jekyll-site/
├── _config.yml          ← remote_theme: mmistakes/minimal-mistakes
├── _posts/              ← your content
├── _pages/              ← your pages
├── _data/               ← your data files
├── _layouts/            ← any layout overrides
├── _includes/           ← any include overrides
├── _sass/               ← custom styles
└── assets/
    └── images/          ← your images

The theme provides the layout, CSS, and JavaScript. You provide the content and any customisations. The separation is clean.

Common remote theme issues

Build fails: “Remote theme error”

The most common cause is a rate limit on the GitHub API. Remote themes fetch from GitHub at build time; too many builds in a short window can hit unauthenticated API limits.

Fix: Set a GITHUB_TOKEN environment variable in your build platform. This uses authenticated API requests with higher limits:

# Netlify / Cloudflare Pages environment variable
GITHUB_TOKEN: your_github_personal_access_token

Theme files not updating

If you pinned to a branch (@main) and updated the remote theme, old cached files may still be served. Clear your build platform’s cache or pin to the latest commit SHA.

CSS not loading after customisation

Check your baseurl in _config.yml. Remote themes often have hardcoded paths that conflict with a non-empty baseurl. For a root-domain site, baseurl: "" is correct.

Layout not found

If you reference a layout that exists in the remote theme but get a “layout not found” error, ensure jekyll-remote-theme is listed in your plugins array (for non-GitHub Pages platforms) and in your Gemfile.

Switching themes

Switching remote themes is as simple as changing one line in _config.yml:

# Before
remote_theme: mmistakes/minimal-mistakes

# After
remote_theme: pages-themes/cayman@v0.2.0

Rebuild your site. The new theme applies immediately. Note that any layout names, front matter variables, or configuration keys specific to the old theme may not exist in the new one — you will likely need to update those as well.

Remote themes on GitHub Pages

GitHub Pages enables jekyll-remote-theme by default since 2017. Any public GitHub repository with a valid Jekyll theme structure can be used as a remote theme.

This is particularly useful for using themes that are not on the GitHub Pages gem whitelist — which only includes about 15 official themes. With remote_theme, the entire Jekyll ecosystem is available.

Remote themes are one of the easiest ways to get a professional Jekyll site up and running quickly. Combined with selective file overrides and _config.yml customisation, you can build a unique site on top of a polished theme foundation without managing hundreds of theme files yourself.