Installing Jekyll on Windows

Library

CC 2.0 image courtesy Fredrik Rubensson on Flickr

I have wanted to experiment with Jekyll for some time but I was hampered because Jekyll is a Ruby Gem. Granted, I could have created an Azure VM with a Linux distro but I wanted something native on my machine. So, I was excited to see in the official Jekyll installation docs that a workaround for running Jekyll on Windows 10 exists.

The process has been highlighted in other blog posts (see Resources). My article is not an attempt to replicate their work, but rather to expand on it with my own observations as I go through the process of understanding Jekyll.

Jekyll Overview

Jekyll_logoJekyll is a simple, blog-aware static site generator that converts raw text files into a ready-to-use, database-free static website that can be served up by any web server. They can vary from one-page websites to those that are more sophisticated. A static site generator creates all website pages once there’s a change to the site and before they are pushed to a web server. This means that sites are more performant, cached easier, and are more secure.

Jekyll is open source and easy to use. It is in use at companies such as Bootstrap, Atlassian Design, and Mongo DB for their own websites and documentation pages. Similar static site generator projects include Hugo, Hexo, Middleman, and Sphinx. Jekyll is also the engine behind GitHub Pages. This means when you create a GitHub page for your project or website you are natively using Jekyll.

Installing Chocolatey

Chocolatey_logoThe quickest way to get Jekyll on your Windows system is via Chocolatey, a package manager for Windows. It is like apt-get or yum for Linux. Chocolatey is built on the NuGet infrastructure and works with PowerShell to install applications and tools quickly via the command line. A Chocolatey package holds everything required to manage a piece of software within one deployment artefact. It also understands both versioning and dependency requirements.

To install Chocolatey, make sure your machine meets the following requirements:

  • Windows 7+ / Windows Server 2003+
  • PowerShell v2+
  • .NET Framework 4+ (the installation will try to install .NET 4.0 if not present). Note that Visual Studio is not required to install Chocolatey.
  1. Open Windows PowerShell with elevated Administrator permissions.
    • Click the Windows Key + S and search for PowerShell.
    • Right-click Windows PowerShell in the search results and select Run as administrator.

    Jekyll01

  2. Before running any PowerShell commands, make sure your PowerShell ExecutionPolicy is not restricted. If the execution policy is restricted (the default in Windows 8, Windows Server 2012, and Windows 10) then script files may not be permitted to run. To change execution policies, run the following two commands in the open PowerShell window first:
    • Set-ExecutionPolicy Unrestricted
    • Set-ExecutionPolicy RemoteSigned

    If you want to revert PowerShell to its original restricted policy to prevent future scripts from running, use:

    • Set-ExecutionPolicy Restricted
  3. It’s now time to install Chocolatey. Run the following command in PowerShell:

    Chocolatey should install as shown in the image below:

    Jekyll02

  4. Wait a few minutes for Chocolatey to finish installing. Once complete, close the PowerShell window to ensure no resources are held in memory.
  5. Re-open PowerShell with elevated Administrator permissions.
  6. Run the following command to find the version of Chocolatey installed:
    • choco version

    As of this writing, the current version of Chocolatey is v0.10.3.

Installing Ruby

Ruby_logoRuby is the open source programming language used to build Jekyll. We need to install Ruby via Chocolatey before we can install Jekyll. We need Ruby installed with:

  • Ruby version 2.0 or above
  • RubyGems (a package manager for distributing self-contained Ruby programs and libraries called a “gem”)
  1. Using Chocolatey, install Ruby with the following command in the PowerShell window:
    • choco install ruby
  2. Hit y to run the Ruby script.
  3. Wait a few minutes for Ruby to finish installing. Once complete, a success message appears stating Ruby was installed to ‘C:\tools\ruby23’.Jekyll03
  4. Close PowerShell to ensure no resources are held in memory.
  5. Re-open PowerShell with elevated Administrator permissions.
  6. Run the following command to find the version of Ruby installed:
    • ruby -v

    As of this writing, the current version is ruby 2.3.1p112 (2016-04-26 revision 54768).

Installing Jekyll

The best way to install Jekyll is through RubyGems. To install Jekyll and its dependencies, follow the steps below:

  1. Type the following command in the PowerShell window to install the RubyGem Bundler:
    • gem install bundler
  2. Wait a few minutes for RubyGem Bundler to finish installing.Jekyll05
  3. Type the following command in the PowerShell window to install Jekyll:
    • gem install jekyll
  4. Wait a few minutes for Jekyll to finish installing. Once complete, close the PowerShell window to ensure no resources are held in memory.
  5. Re-open PowerShell with elevated Administrator permissions.
  6. Run the following command to find the version of Jekyll installed:
    • jekyll -v

    As of this writing, the current version is jekyll 3.4.0.

SSL Connection Error

While trying to install the two gems above you might see the following SSL Connection error message in PowerShell:

ERROR: Could not find a valid gem 'bundler' (>= 0), here is why:
Unable to download data from https://rubygems.org/ - SSL_connect returned=1 errno=0 state=SSLv3 read server certificate B: certificate verify failed (<a href="https://api.rubygems.org/specs.4.8.gz">https://api.rubygems.org/specs.4.8.gz</a>)

As the error message states, a verified SSL certificate could not be found. To solve this issue, go through the steps under Installing Using Update Packages on the following page: SSL Certificate Updates

By following these steps, you can circumvent this error by manually downloading and updating your local version of RubyGems. This will update the certificate and allow you to proceed with the installation via PowerShell.

Once the steps are complete, you can install both the Bundler and Jekyll.

Jekyll04

Summary

In this article, we have seen how to setup Jekyll inside a Windows 10 environment. This involved deploying both Chocolatey and Ruby onto our environment as a platform for Jekyll.

In a future article, we will see how to create our first Jekyll site and serve it via IIS or Azure.

Resources

Advertisements

About Ken Cenerelli
I am a Programmer Writer, .NET Developer, Microsoft MVP - Visual Studio and Development Technologies, Public Speaker, Blogger, and Microsoft Azure Nerd. I blog regularly at kencenerelli.wordpress.com and can be found on Twitter via @KenCenerelli.

5 Responses to Installing Jekyll on Windows

  1. Pingback: Running Jekyll on Windows & Azure | Ken Cenerelli

  2. Ken, any reason that we shouldn’t use Install-Package Chocolatey (PackageManagement)?

  3. When I ran “gem install bundler”, I got a “Could not find a valid gem bundler” error. It was looking for an https site. To fix this, as suggested on StackOverflow, I ran the following:

    gem sources -a http://rubygems.org
    gem install bundler

    References:
    http://stackoverflow.com/questions/19132450/error-installing-bundler
    http://stackoverflow.com/questions/8845432/how-to-install-rvm-on-windows-7/8845445#8845445

    Hope this helps someone!

  4. June – I am glad you got this figured out and thanks for the supplemental links that solved your issue! All the best.

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: