How to install Jekyll and pages-gem on Windows (x64)

Jekyll is an awesome static file generator and it is really easy to create a blog with the generator. My current blog is built with Jekyll and you can find the jekyllDecent theme on GitHub.

It only takes minutes to create your own blog and run it on Windows.

System Prerequisites

Install a package manager for Windows called Chocolatey
Install Ruby via Chocolatey: choco install ruby -y
Reopen a command prompt and install Jekyll: gem install jekyll

Setup a Blog

Open a command prompt at C:\
Create a blog jekyll new myBlog
Change the location cd ./myBlog
Use the command jekyll s to serve/host the blog

Play time

Now you can browse to http://127.0.0.1:4000 and visit your new blog. If you like to start changing your blog, I recommend you have a look at the Jekyll getting started guide.

GitHub pages and plugins

If you like what you saw you might know that you can host your blog on GitHub pages.

GitHub Pages is deeply integrated with Jekyll, a popular static site generator designed for blogging and software documentation, [..]

—help.github.com

GitHub will automatically generate your blog if you deploy the source code to the gh-pages branch of your repository. But the thing with GitHub is that you cannot run any plugin that is available for Jekyll. GitHub only allows a few plugins to run. GitHub has bundled the available plugins into a Ruby gem that can be installed via command line. The problem on Windows (x64) is that this is the point there it gets complicated.

How to install github-gem

I assume that you have installed Chocolatey on your system. If you have a version of Ruby installed already you need to uninstall it. We need a specific version!

Install Ruby and Ruby development kit

Open a elevated command prompt and execute the following commands:

choco install ruby -version 2.2.4
Reopen an elevated command prompt
choco install ruby2.devkit - needed for compilation of json gem

Configure Ruby development kit

The development kit did not set the environment path for Ruby so we need to do it.

Open command prompt in C:\tools\DevKit2
Execute ruby dk.rb init to create a file called config.yml
Edit the config.yml file and include the path to Ruby - C:/tools/ruby22
Execute the following command to set the path: ruby dk.rb install

Nokogiri gem installation

This gem is also needed in the github-gem. Continue with the next step and if you get errors about Nokogiri follow this steps.

Note: In the current pre release it works out of the box with Windows x64 but this version is not referenced in the github-gem.

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 --^
   --with-xml2-include=C:\Chocolatey\lib\libxml2.2.7.8.7\build\native\include^
   --with-xml2-lib=C:\Chocolatey\lib\libxml2.redist.2.7.8.7\build\native\bin\v110\x64\Release\dynamic\cdecl^
   --with-iconv-include=C:\Chocolatey\lib\libiconv.1.14.0.11\build\native\include^
   --with-iconv-lib=C:\Chocolatey\lib\libiconv.redist.1.14.0.11\build\native\bin\v110\x64\Release\dynamic\cdecl^
   --with-xslt-include=C:\Chocolatey\lib\libxslt.1.1.28.0\build\native\include^
   --with-xslt-lib=C:\Chocolatey\lib\libxslt.redist.1.1.28.0\build\native\bin\v110\x64\Release\dynamic

Install github-gem

Open command prompt and install Bundler: gem install bundler
Create a file called Gemfile without any extension in your root directory of your blog
Copy & past the two lines into the file:

source 'http://rubygems.org'
gem 'github-pages'

Note: We use an unsecure connection because SSL throws exceptions in the version of Ruby
Open a command prompt in your root directory
Install github-pages: bundle install

Conclusion

After this process you should have github-pages installed on your system and you can host your blog again with jekyll s.
There will be a warning on startup that you should include gem 'wdm', '>= 0.1.0' if Gem.win_platform? to your Gemfile but I could not get jekyll s working if I include that line so for the moment I ignore that warning.

If you can wait 2-3 months, the installation process of the github-gem should be as simple as the setup of the blog. But as long as the new version of the Nokogiri (v1.6.8) is not stable and referenced it is work to get it up and running on Windows.

Jens Willmer

Tutorials, projects, dissertations and more..