Custom Jekyll theme without Gems

I am at a complete loss to understand how to create a Jekyll theme that can be used both locally and on GitHub Pages. As I understand it, I should not use themes packaged in Gems as GitHub places restrictions on these but when I try to create and use a standalone theme, Jekyll seems to insist on a default theme if none is specified. I have been unable to find a way of packaging my theme without using Gems so that it can be picked up by Jekyll. I am running the latest version of Jekyll locally on Ubuntu 20.04 in preparation for deploying my site to GitHub when everything is ready.

I’m not sure if I understand you correctly, but you can use Jekyll completely without a theme. Everything can also directly be specified in _config.yml, CSS/SCSS files and layouts. That’s how I run my site with >200 pages and very different sections. Best, Michael

@caolin The procedure is very simple when you know what you want.
To re-iterate your use-case, you desire to:

  • develop a jekyll theme that is usable locally and on GitHub Pages
  • not package the theme as a Rubygem.

There are two ways to accomplish this:

  • classic Jekyll site — the theme and site source files co-exist in the same repository
  • remote-theme — the theme and site source files are in two separate repositories

The classic way was how Jekyll sites got built by default prior to theme-gem support. You can still follow this structure as it easier to maintain as layouts and Markdown files are at same place…

With the remote-theme way, you use a plugin named jekyll-remote-theme and link your site’s repository to a public theme repository hosted on GitHub. The advantage of this route is that your site contents are just your Markdown files.

Regarding the issue you are facing, you can only use the config key theme for a Ruby gem.
When using the remote-theme plugin, you use the config key remote_theme instead. Details can be found at: