Jekyll Remote Themes: How to Use Any GitHub Theme Without Installing It

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:

Theme	`remote_theme` value	Best for
Minimal Mistakes	`mmistakes/minimal-mistakes`	Blogs, documentation
Just the Docs	`just-the-docs/just-the-docs`	Documentation
Cayman	`pages-themes/cayman@v0.2.0`	Project pages
Slate	`pages-themes/slate@v0.2.0`	Project pages
Minima	`jekyll/minima`	Simple blogs
al-folio	`alshedivat/al-folio`	Academic portfolios

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:

Copy the file from the theme’s GitHub repository
Place it at _layouts/post.html in your project
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 "{{ site.theme }}";

// 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

	Remote theme	Gem theme	Downloaded theme
Files in your repo	No	No	Yes
Easy updates	Yes (change one line)	Yes (update gem version)	No (manual)
Full customisation	Yes (override files)	Yes (override files)	Yes (edit directly)
Works on GitHub Pages	Yes	Whitelist only	Yes
Requires internet at build	Yes	No	No
Build time impact	Slightly slower	Minimal	Minimal

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.

Customising a remote theme beyond `_config.yml`

The _config.yml approach to customisation works for the settings the theme author exposed, but themes inevitably have behaviour you want to change that has no config option. Jekyll’s file override mechanism handles this: any file you place in your repository with the same path as a theme file takes precedence over the theme file. You do not need to copy the entire theme — only the specific file you want to change.

To find the correct path for a file you want to override, clone or browse the theme repository on GitHub. If you want to override the navigation include, look for _includes/navigation.html in the theme repo and create _includes/navigation.html in your own repository with your modified version. Jekyll will use yours. The remote theme’s version of that file is effectively shadowed.

This selective override approach is vastly preferable to forking the theme. A fork requires you to manually pull upstream changes whenever the theme author releases improvements. With remote theme plus overrides, you always get the latest version of the theme’s files — except for the specific files you’ve chosen to take control of. When the theme author releases a breaking change to a file you’ve overridden, you’ll need to review and update your version, but that is a much smaller surface area than maintaining a full fork.

Custom Sass overrides follow a similar pattern. Many themes include a _sass/custom.scss or assets/css/main.scss file specifically designed to be overridden. Copy that file into your repository and add your custom CSS there. If the theme doesn’t have a dedicated override file, create assets/css/main.scss in your repo and import the theme’s stylesheet before adding your overrides — @import "{{ site.theme }}/assets/css/main" at the top, then your custom rules below.

Performance implications of remote themes

Remote themes are fetched from GitHub at build time, which adds a network request to every build. For continuous deployment pipelines building on push, this is rarely a problem — the fetch is fast and the build platform caches the result. But for local development, every bundle exec jekyll serve with a remote theme triggers a network request, which can be slow on unreliable connections.

The standard workaround is to use the gem-based version of the theme locally. Install the theme gem in your Gemfile, comment out remote_theme in _config.yml and uncomment the gem-based theme: setting, and use that for local development. Revert to remote_theme for production. A .env file or environment-variable-driven _config.yml makes switching seamless.

For build platforms like Netlify and Cloudflare Pages, dependency caching (caching the vendor/bundle directory between builds) means the remote theme is typically fetched only once and then served from cache on subsequent builds. Configure caching in your build platform’s settings to reduce build times for remote-theme sites.

Security considerations

Remote themes pull code from a third-party GitHub repository. The theme files — Liquid templates, JavaScript, CSS — execute in the context of your site build and are served to your readers. A compromised theme repository could, in theory, serve malicious content.

Mitigate this risk by pinning to a specific commit SHA rather than a branch name. With @main, you always get the current state of the main branch — which could change at any time. With @a1b2c3d (a commit SHA), you get exactly that commit forever. The trade-off is that you must manually update the SHA to receive updates.

For business-critical or security-sensitive sites, consider auditing the theme repository code before pinning. Popular themes maintained by reputable developers (Minimal Mistakes by Michael Rose, Just the Docs by Patrick Marsceill) have large user bases and public issue trackers that would surface any supply chain compromise quickly. Small or abandoned theme repos warrant more scrutiny before use in production.

When to move from remote theme to local theme

Remote themes are excellent for getting started quickly and for sites where you want to track upstream theme improvements. But there are clear signals that you should take full ownership of the theme files:

You have overridden more than a quarter of the theme files. At that point, you are essentially maintaining a fork anyway — tracking the remote theme’s changes while managing extensive overrides creates more complexity than owning the code outright.

The theme is no longer actively maintained. An unmaintained remote theme will eventually break as Jekyll versions advance or GitHub Pages updates its build environment. If the repository has been inactive for over a year and has open issues about build errors, download a snapshot and commit it to your repository rather than depending on the remote.

You need features that require changes to theme files that cannot be achieved through overrides alone. Some theme architectures make certain kinds of customisation impossible without modifying core files. When you reach that ceiling, local ownership is the right call.

Transitioning from remote theme to local is straightforward: run bundle exec jekyll build once with the remote theme configured, then copy the theme’s gem files from your Ruby gem cache into your repository. Or clone the theme repo and copy its files in. From that point on, your site is fully self-contained.