Fixing Jekyll Serve On Windows13 Feb 2017
While there are several guides for installing jekyll for Windows (official github pages article, Run Jekyll on Windows) They seem to skip some key points that have given me trouble with the latest version of ruby (2.3.3 as of this writing) on Windows 10.
Having struggled through this twice now on two separate Windows installations, I’m making this guide so that at least I’ll be able to refer to it quickly. I hope it helps anyone else that has issues getting
jekyll serve to just work as intended.
What This guide covers:
- The setup required to serve existing jekyll projects on Windows 10.
- Errors while compiling the json gem in Ruby.
- Errors regarding SSL authentication when trying to run
- Errors regarding Github Authentication when trying to run
What this guide does NOT cover:
- How to create a new Jekyll project or how to use Github pages.
If you would like to learn how to make a new Github Pages Jekyll Project please see step 2 and 3 in the official github pages guide, or look into other tutorials. For example:
1. Install all Jekyll Dependencies
First we need to make sure that we have all dependencies for Jekyll on Windows 10. If you have Ruby, Ruby Development Kit and Bundler already installed and working, feel free to skip down to the 2. Get Jekyll Server Working section below.
This guide assumes that you know how to modify the PATH and set environment variables. I highly recommended the free Windows Environment Variables Editor which greatly improves that experience over the default Windows Environment variable UI, even in Windows 10.
Run the installer, and install in the default location. For 2.3.3 64bit this would be
During the installation make sure to have ruby added to the path, or do so manually by adding
C:\Ruby23-x64\bin to your path.
You can verify that your path has been modified correctly by opening a new command prompt and typing (a command prompt that was open previously will not yet have the new PATH):
Install Ruby Development Kit
The latest direct download link as of this writing is: DevKit-mingw64-64-4.7.2-20130224-1432-sfx.exe (located on the download page in the Other Useful Downloads > DEVELOPMENT KIT section).
When you run the executable it will simply ask you for a directory to extract to. DO NOT EXCTRACT TO YOUR DOWNLOADS FOLDER, which will dump dozens of files. Instead provide a path next to the ruby installation such as
You need to first initialize and then bind the devkit to your Ruby installation. Open a command prompt and navigate to the newly extracted folder:
Then to initialize the devkit run:
ruby dk.rb init
Finally install and bind the devkit to your ruby installation:
ruby dk.rb install
Install bundler with:
gem install bundler
Install the Gems for a Github-pages project
As mentioned earlier, this guide assumes you have already created a github pages jekyll site that you’ve cloned on your windows machine and want to serve locally. Your project should contain a Gemfile that contains at least the following:
source 'https://rubygems.org' gem 'github-pages', group: :jekyll_plugins gem 'wdm', '>= 0.1.0' if Gem.win_platform?
With a command prompt cd into the directory containing the
Gemfile and use bundler to install the github-pages jekyll dependencies:
2. Get Jekyll Server Working
This is where most tutorials leave off and where the majority of my frustration in getting Jekyll to serve on Windows 10 started.
At this point, the offical guide claims that you should be able to just run:
And that should work.
However on two separate Windows 10 Instances I have had problems here. Here is what I had to do:
Fix SSL “certificate verify failed”
Apparently this is a long-standing Issue with Ruby on Windows. You can read more about it here: https://gist.github.com/fnichol/867550
It boils down to the OpenSSL library that Ruby uses not including SSL certificate authorities in a file so we will install it using an Environment Variable.
First, download the
cacert.pem file from http://curl.haxx.se/ca/cacert.pem
This file will need to be stored in a permanent location. Since we already have
C:\RubyDevKit, I’d recommend creating a folder for it there, for example
cacert.pem to that folder.
Now we need to set up an environment variable named
SSL_CERT_FILE. To do so with Eveditor, launch the program and click ‘System variables’ in the left sidebar and click the ‘Run as administrator’ button to restart the program with elevated priviledges.
Now click ‘New’ In the menu bar, then at the bottom enter
SSL_CERT_FILE as the
Name and the full path for the file for the
Value, which in my case is
Make sure to click the
Set button, and you’re good to go. Note that if you have an open command prompt it will need to be re-launched to load the new variable.
However keep your environment variable editor open, because there is one more thing you may need to set.
Fix “No repo name found”
Now when you run
jekyll serve you may see this error:
ERROR: YOUR SITE COULD NOT BE BUILT: ------------------------------------ No repo name found. Specify using PAGES_REPO_NWO environment variables, 'repository' in your configuration, or set up an 'origin' git remote pointing to your github.com repository.
It should be noted that my project’s
.git/config does have an ‘origin’ git remote pointing at my github.com repository, but for some reason that is not enough. While environment variables are fun, they are not portable, so I chose to modify my
_config.yml file instead to define the
Simply add a
repository key with value
<USERNAME>/<REPOSTIROY_NAME> on a new line anywhere in the
_config.yml file, which in my case was:
Fix “The GitHub API credentials you provided aren’t valid.”
When trying to run
jekyll serve you may see one of these errors:
Error: The GitHub API credentials you provided aren't valid.
GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.
This can be due to having 2-factor authentication set up on github, or the credentials not stored otherwise. The easiest fix for this is to generate a unique
Personal Access token through github’s website, and store that in the
JEKYLL_GITHUB_TOKEN environment variable.
To generate a new access token for Jekyll visit https://github.com/settings/tokens, then click ‘Generate new token’.
Token description enter something so you know what it is being used by. I named mine
Select scopes simply check the
When you click
Generate Token, you will see the token at the top of the page (screenshot is of a dummy token of course):
Make sure to either leave that open or copy and paste it in a new notepad++ tab, since you will never be able to see it again once you navigate away from that page.
Open your favorite environment variable editor and create a new System Variable. for
JEKYLL_GITHUB_TOKEN and for
Value paste in the new token.
Make sure that you did not accidentally copy any spaces to either side of the token! Make sure to hit
Set to save the token, and re-open your command prompt so that it reloads the env vars.
Fix jekyll-remote-theme/libcurl dependency error
Lastly, you may get a dependency error that states:
Dependency Error: Yikes! It looks like you don't have jekyll-remote-theme or one of its dependencies installed. In order to use Jekyll as currently configured, you'll need to install this gem. The full error message from Ruby is: 'Could not open library 'libcurl': The specified module could not be found. . Could not open library 'libcurl.dll': The specified module could not be found. . Could not open library 'libcurl.so.4': The specified module could not be found. . Could not open library 'libcurl.so.4.dll': The specified module could not be found.' If you run into trouble, you can find helpful resources at https://jekyllrb.com/help/!
As of the time of this writing (January 2018), this is will occur if you are using the github-pages gem on Windows, because v171 of the gem added the default theme
jekyll-remote-theme as a dependency which in turn requires
For more info please refer to the relevant issue on the github pages gem bug tracker: https://github.com/github/pages-gem/issues/509
Hopefully future updates of this gem will remove the dependency, but for the time being you have two options:
- Install the libcurl dependency yourself.
- Modify your Gemfile to force version 170 which doesn’t have this dependency.
For the time being I chose to do the latter, and so in my Gemfile I changed
gem 'github-pages', '170'
And with that,
jekyll serve should finally work as intended: