Jekyll Remote Theme

Jekyll Remote Theme is a Jekyll plugin that lets a site build with any public GitHub-hosted Jekyll theme instead of a locally installed gem theme, selected through the remote_theme config key. It is maintained by Ben Balter, is supported on GitHub Pages, and ships as the jekyll-remote-theme Ruby gem.

What is Jekyll Remote Theme?

Jekyll Remote Theme takes a remote_theme value in a site's _config.yml pointing at a GitHub repository (such as pages-themes/cayman), downloads that repository's theme files, and applies them to the site during the Jekyll build. It runs anywhere Jekyll runs, including GitHub Pages, and is distributed as a Ruby gem. You do not need to upload the theme to RubyGems or include a .gemspec file for it to work.

Key Features

• Remote theme resolution — the remote_theme key accepts public GitHub themes in OWNER/REPOSITORY form.
• Ref pinning — append @ plus a branch, tag, or commit (for example pages-themes/cayman@v0.2.0); branch names with slashes such as OWNER/REPOSITORY@feature/new-layout also work. Without a ref, HEAD is used.
• Latest release mode — @latest fetches the most recent release from the GitHub Releases API and falls back to HEAD if no releases exist.
• GitHub Enterprise support — enterprise themes use the form http[s]://GITHUBHOST.com/OWNER/REPOSITORY; the hostname must be allowed via PAGES_GITHUB_HOSTNAME or GITHUB_HOSTNAME, and the codeload subdomain must be reachable.
• Local path themes — relative or absolute local directories can serve as themes for local development, though local paths are rejected in safe mode (including GitHub Pages).
• File-level overrides — any theme layout, include, Sass file, or asset can be overridden by creating the same path in your site; only overridden files use your local versions.
• GitHub Pages compatible — the plugin is explicitly supported on GitHub Pages.

Who is it for?

• GitHub Pages site owners: apply a published theme like pages-themes/cayman to a project or blog without vendoring theme files.
• Theme authors: let users consume a theme directly from its GitHub repository, with no RubyGems publishing or gemspec.
• Jekyll developers testing overrides: point remote_theme at a local directory to iterate on layout, include, and Sass overrides before pushing.

How does Jekyll Remote Theme work?

Add the gem to your Gemfile, list jekyll-remote-theme under plugins in _config.yml (use gems on Jekyll versions below 3.5.0), then set remote_theme to the target repository. On build, the plugin downloads and extracts the theme from GitHub and merges it with your site, with local files taking precedence for matching paths.

FAQ

Does Jekyll Remote Theme work on GitHub Pages?

Yes. The plugin is documented as supported on GitHub Pages, which is why the pages-themes repositories are the common example values for remote_theme.

Can I pin a theme to a specific version?

Yes. Append @ and a branch, tag, or commit after the repository name, or use @latest to track the newest GitHub release, falling back to HEAD when no releases exist.

Can I use a local theme directory?

Yes, for local development only. Relative or absolute paths work, but local paths are not available in safe mode, which includes GitHub Pages builds.

Does it work with GitHub Enterprise?

Yes, using the full GITHUBHOST.com/OWNER/REPOSITORY URL form. You must set PAGES_GITHUB_HOSTNAME or GITHUB_HOSTNAME to the enterprise hostname, and the codeload subdomain must be reachable for downloads.