How to specify a theme in _config.yml that's on local file system

This is going to seem silly and I’m sure I’ll be kicking myself when someone points out the obvious solution. But, here goes…

I have a couple websites that use the same theme that’s created by someone else. He has a github public repo and he’s made the theme installable as a gem. Everything is peachy. I can use it as a remote_theme or use the gem that’s in the bundle.

Now, I want to fork the theme and do my own thing with it. Easily enough, I just point remote_theme at my own github repo and off I go. Except that’s really slooooow. It goes from 4 seconds to build up to about 45 seconds, just with the one change. I can edit the theme that’s down inside my bundle folder but that’s really ganky.

What I want to do is point the _config.yml that’s on my local machine, to the clone of what I forked and is in my own repo and on my local drive, one level above my website project.

So, instead of
remote_theme: myGHUser/awesome-theme-my-version
I want to use
theme: ../awesome-theme-my-version
Only that second one doesn’t work for me.

Please point out that I’m an idiot and show me the correct way to do this. Eventually, I’ll point the config to my repo as a remote theme, but I’m in the design/build phase right now and those builds are killing me.


I’m going to leave this question here, but I’ve somewhat answered the question for myself. Not in figuring out how to specify a local path, but I’ve cut the build time with the remote theme down to about 6-7 seconds.

When I forked the original repo from the theme author, I included his embedded test project and all the assets that went with it. To make it worse, my .gitignore didn’t prevent the vendor folder from getting included, so the remote repo was ~50MB.

I cloned the forked theme repo, removed all the extra cruft, put in a proper .gitignore, and pushed back to github under a modified name. Now the remote theme pull takes only 1-2 seconds. I left the original README content and made sure to credit the original author in the cloned modified repo.

I’d like to test my changes to the theme locally before pushing the theme back to github, but this is a compromise that I can live with.

Jekyll’s theme setting is the name of a Gem, so to use a local one, you’d specify a Gem with a local path in your Gemfile. Something like:

gem "mytheme", path: "/path/to/mytheme"

There’s also a local mechanism built into bundler to force the use of a local, rather than remote, git clone. See: Using Bundler with Local Git Repos


If you are not using plain GH Pages and can use custom themes, why not use this approach.

Here I point to my theme which is a GitHub repo. It gets fetched once on bundle install.

gem "fractal", git: ""


theme: fractal

And then when I serve I can use the gem in local vendor directory without having to use remote theme.

Of course you have to do a bundle update to get the latest repo contents if you update on GitHub. So it’s not a local based solution.

I also find that useful when I do use the remote theme plugin but it complains that a dependency of the theme is not installed locally

So by doing this, I force dependencies like jekyll-sitemap to be installed without listing them explicitly.

gem "fractal", git: ""

group :jekyll_plugins do
  gem "jekyll-remote-theme", "~> 0.4.2"


remote_theme: MichaelCurrin/fractal
1 Like

It’s not a GH page. It’s in an S3 bucket, served with CloudFront. I’m an embedded/C/C++ developer, so Ruby and its’ supporting tools aren’t my strong suit.

I like your idea of using a gem, but I haven’t made a proper release. It’s just for my own use, although it’s a public repo. I can’t imagine anyone else wanting my style or layout changes–they can use the parent project, which is updated quite frequently.

Okay thanks.

Yeah even you are the only one who uses the theme and it’s a public repo, that is still fine.

Using S3 and CloudFront and copying to S3 is a rather manual deployment flow. Plus you have to deal with clearing cache on a deploy, and where to site gets built.

The modern flows make things easy. Check Jekyll docs Deployment | Jekyll • Simple, blog-aware, static sites

Netlify is amazing. You connect it to a public or private repo and specify a build command and build directory and it builds and deploys your site on every commit. No manual control over builds and S3 needed.

And GitHub Actions as well does something similar but needs a longer config.

Most of my sites use GitHub Pages and no build config. But GitHub takes care of Ruby and Jekyll and site building for me. No need to copy assets myself. Just push to GitHub and the site gets deployed.

You can also hook up your custom domain to GH Pages or Netlify at no cost.

Thanks for the tips on this.

I need to update my build process. I keep a bash script to do the clean, build, s3 sync, and cloudfront invalidate. The sites I have using that theme are small vanity sites with me as the only author, but I should strive to do better. It would be nice in a pinch to be able to use the Github site to add a page directly from my tablet and let github or netlify build it rather than having to wait until I have my laptop handy.

edit: Thanks @MichaelCurrin. I created an account on netlify and hooked up my repos to it. All built on the first try, so I pointed my Route53 domains over to netlify. That was painless. Now testing that my links still work.

1 Like

That’s great to hear. Another pro tip is to enable building feature branches as preview deploy URLs so you can check the content before merging. And you can add a Netlify status badge to your README to make it easier to check the build is passing.

If you use JS in your Jekyll site, your build command could be

build: npm run build && bundle exec jekyll build --trace 

The Netlify user on GitHub has some one click deploy repos too so you can add a given repo to your own and deploy it, including Jekyll CMS.