Setting up Jekyll and GitHub Pages successfully on Windows
Right, so, this is a tricky one. I’ve read around the web that quite a handful of people run into issues when they try to set up Jekyll locally on their Windows machines. As a matter of fact, I read about someone who switched over to Mac in order to get Jekyll running. The problem is that the Jekyll documentation isn’t a silver bullet, and you often end up tweaking and turning in order to get it fully working.
So here comes a step-by-step guide that I worked out, and which I got working on all of my Windows 10 machines. Enjoy!
- The end goal here is setting up a blog on the web, so you’ll need a site to host your blog. GitHub Pages is a great alternative. Go ahead and go through the steps outlined by GitHub.
- Install Chocolatey.
Install Ruby by starting cmd and:
choco install ruby -version 2.2.4
Download Ruby DevKit for Ruby 2.0 and above. Open the executable and extract the content to:
Start cmd from C:\tools\DevKit2 and:
ruby dk.rb init
Edit the config.yml file by adding the following to it:
From cmd, run:
ruby dk.rb install
Start cmd and:
gem install jekyll
Error 1: Old Ruby development kit is installed.
Solution: Download and install the newest version of the RubyInstaller here. Make sure to choose option 3 when installing MYSYS2:
Error 2: Could not find a valid gem ‘jekyll’ (>= 0), here is why: Unable to download data from https://rubygems.org/ […].
gem sources --remove https://rubygems.org/
gem sources -a http://rubygems.org/
gem install jekyll
Error 3: ‘make’ is not recognized as an internal or external command.
Solution: Install Make for Windows and add the make.exe folder path to PATH in environment variables.
Set site generation encoding from cmd:
Install Nokogiri gem for GitHub Pages from cmd:
cinst -Source "https://go.microsoft.com/fwlink/?LinkID=230477" libxml2
cinst -Source "https://go.microsoft.com/fwlink/?LinkID=230477" libxslt
cinst -Source "https://go.microsoft.com/fwlink/?LinkID=230477" libiconv
gem install nokogiri
Error: Failed to install
Solution: Simply skip it.
Install GitHub Pages from cmd:
gem install bundler
Create an empty file called Gemfile in the root directory of your blog and add the following to it:
gem 'wdm', '>= 0.1.0' if RbConfig::CONFIG['target_os'] =~ /mswin/i
In the root directory of your blog, from cmd, run:
If you get any error here, try
bundle update, then again
Jekyll and GitHub Pages are now fully installed on your system. To create a new Jekyll template site, run from cmd:
bundle exec jekyll new . --force
To launch the Jekyll site, run from cmd:
bundle exec jekyll serve
Go to http://localhost:4000/ to see your site.