Running Jekyll with GitHub Pages using Windows 8.1 x64 and Ruby 2.0 x64

Published:

I had some problems running Jekyll locally on a Microsoft Windows 8.1 x64 host together with Ruby 2.0 x64. In this blog post I describe all steps required to get Jekyll with GitHub Pages up and running.

  1. Install Ruby 2.0 x64 using RubyInstaller (direct download link).
  2. Add the directory <path_to_ruby>\bin (e. g. C:\ruby\bin) to the PATH environment variable.

     SET PATH=%PATH%;C:\ruby\bin
    
  3. Install DevKit x64 (direct download link).
  4. Install Bundler using RubyGems.

     gem install bundler.
    
  5. Create a file Gemfile in the directory <path_to_jekyll_blog> with the following content:

     source 'https://rubygems.org'
     gem 'github-pages'
    
  6. Run bundle install. This will possibly fail, since the installation of the gem nokogiri has problems with Microsoft Windows 8.1 using Ruby 2.0. If the following error message is printed to the standard output, additional installation steps are required (see below):

     An error occurred while installing nokogiri (1.6.1), and Bundler cannot continue.
    
  7. Install Chocolatey by running the following command in cmd.exe:

     @powershell -NoProfile^
       -ExecutionPolicy unrestricted^
       -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))"^
       && SET PATH=%PATH%;%systemdrive%\chocolatey\bin
    
  8. Install libxml2, libxslt, libiconv and dependencies using Chocolatey:

     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
    

    Credits for this step go out to the StackOverflow user Chloe, who described this in an answer to this StackOverflow question

  9. Install Nokogiri using RubyGems.

     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 The following should be printed to the standard output;
    
     This could take a while...
     Successfully installed nokogiri-1.6.1
     Parsing documentation for nokogiri-1.6.1
     unable to convert "\x90" from ASCII-8BIT to UTF-8 for lib/nokogiri/nokogiri.so, skipping
     Installing ri documentation for nokogiri-1.6.1
     1 gem installed
    
  10. Repeat step 6. The installation should succeed now and the following should be printed to the standard output:

    Fetching gem metadata from https://rubygems.org/.........
    Fetching additional metadata from https://rubygems.org/..
    Resolving dependencies...
    Using RedCloth 4.2.9
    Using i18n 0.6.9
    Using json 1.8.1
    Using minitest 5.3.3
    Using thread_safe 0.3.3
    Using tzinfo 1.1.0
    Using activesupport 4.1.0
    Using blankslate 2.1.2.4
    Using fast-stemmer 1.0.2
    Using classifier 1.3.4
    Using colorator 0.1
    Using highline 1.6.21
    Using commander 4.1.6
    Using ffi 1.9.3
    Using gemoji 1.5.0
    Using liquid 2.5.5
    Using rb-fsevent 0.9.4
    Using rb-inotify 0.9.3
    Using rb-kqueue 0.2.2
    Using listen 1.3.1
    Using maruku 0.7.0
    Using posix-spawn 0.3.8
    Using yajl-ruby 1.1.0
    Using pygments.rb 0.5.4
    Using redcarpet 2.3.0
    Using safe_yaml 1.0.2
    Using parslet 1.5.0
    Using toml 0.1.1
    Using jekyll 1.5.1
    Using mini_portile 0.5.3
    Using nokogiri 1.6.1
    Installing html-pipeline 1.5.0
    Installing jekyll-mentions 0.0.6
    Installing jekyll-redirect-from 0.3.1
    Installing jemoji 0.1.0
    Installing kramdown 1.3.1
    Installing rdiscount 2.1.7
    Installing github-pages 17
    Using bundler 1.6.2
    Your bundle is complete!
    Use `bundle show [gemname]` to see where a bundled gem is installed.
    
  11. Run Jekyll via the following command:

    bundle exec jekyll serve
    
  12. Open the website in the default webbrowser:

    start http://127.0.0.1:4000
    

And we are done. Pretty easy and straight-forward, huh?