arthurattwell/Installing-Jekyll-on-Windows.md

## Installing-Jekyll-on-Windows.md

      
    Raw
  

              Installing-Jekyll-on-Windows.md
            
          
    Installing Jekyll on Windows

Getting Jekyll installed on Windows can be more complicated than on, say, OSX and Ubuntu, but not by much. This outlines the steps I use.
I have similar guidance (plus extra steps for my publishing tools) for OSX written up here.
Why is this tricky?

Because each of the pieces that make Jekyll work is fussy, especially on Windows, which the developers of those pieces rarely use.
Most Ruby applications, including Jekyll, comprise original code as well as a bunch of open-source gems built by others. Several of the gems that Jekyll depends on need Ruby to behave in very particular ways. So we need a setup that caters for all of them.
To complicate matters, there are several versions of Ruby, and not all gems work on all versions. Moreover, some gems need code that isn't available in a standard Ruby installation on Windows; they need a special Ruby development kit installed, too.
And finally, Ruby, Jekyll and its dependencies are developing all the time, so in future you may need to experiment with upgrading and downgrading the version of Ruby you're using. You really need a Ruby version manager to make this easier. If you don't use a Ruby version manager, it's very easy to end up confused, with various versions of Ruby on your machine all installed in different ways.
Other options

If you Google 'install jekyll on windows' you'll find a range of approaches. They may well be better than mine.
The official Jekyll guide lists the three main approaches:

Using Ubuntu Bash on Windows. New versions of Windows let you use a Linux subsystem to run Linux software without a virtual machine. This means you can install Linux versions of Ruby and Jekyll, which may be simpler to manage. You then use Jekyll from this special Bash command line.
Using RubyInstaller. RubyInstaller.org provides versions of Ruby that you can install directly on Windows. This used to be the only sensible way to install Ruby in Windows.
Using Chocolatey. Chocolatey is a package manager for Windows that you can use to install versions of Ruby easily.

(The excellent, classic guide to installing Jekyll on Windows by Julian Thilo is unfortunately now outdated.)
There are good guides on installing Jekyll with Ubuntu Bash on Windows from Dave Rupert, Richard Banks, and David Burela. There are useful further tips on this approach from @lucasg.
I don't use that approach because I've found using Ubuntu Bash on Windows to be frustrating: it is still early, largely undocumented software with lots of gotchas. More importantly for me, though, the publishing tools that I maintain need to work out of the box with the Windows Command Prompt.
My approach is built on Jekyll's official docs and Burela's old approach: using Chocolatey plus a dev kit installer.
My experience installing Jekyll on Windows is fairly limited: I've got Jekyll running on a dozen Windows machines over a few years, and the steps below worked for me recently (after trial and error with other approaches) on Windows 10 Professional on a new machine. Your mileage may vary.
Steps

If all goes well, this process should take about 20 minutes. Get a cup of tea and take your time. Don't rush anything. If you get stuck, take time to understand what's going wrong before proceeding or trying another approach. And keep notes on what you're doing, so that if you need to undo what you've done, you're able to retrace your steps.


Unless advised otherwise by installation guides I link to, run these steps in the Windows Command Prompt run as Administrator. To open this admin-level prompt:

click the Windows start-menu button,
type 'Command Prompt' (or just 'cmd'),
right-click the 'Command Prompt' app icon that appears, and
select 'Run as Administrator'.
Windows may ask if you want to let the Command Prompt make changes to your computer: click 'Yes'.


Install Chocolatey. Chocolatey makes it easier to add or remove versions of Ruby on your machine. (There are a few Ruby version managers for Windows, like pik and uru and rvm, but they can go out of date quickly or, like rvm, can be difficult to use.)

Follow the installation steps at chocolatey.org/install carefully.
Check that Chocolatey is installed by running choco --version. If you see the version number, you're all good. Don't proceed if you got errors during the install or don't see the version number.
Close the Command Prompt and open it again as an administrator. Closing and reopening the prompt makes sure that any changes to environment variables made by installation steps are loaded and available in the new prompt.


Install Ruby.
Jekyll now requires at least Ruby v2.4, but we have had problems with Ruby v3. I've been able to install Jekyll and its gems without problems using Chocolatey's Ruby 2.4.1.1 and 2.5.1.2. So, while the following steps show how to install a recent version of Ruby, you can try substituting another Ruby version if you like. See Upgrading Ruby below for more detail on upgrading.

To install, run choco install ruby --version=2.7.0.1. (More details here.)
Check that your desired version of Ruby is installed by running ruby --version.
You can also go and see in File Explorer that Chocolatey has put Ruby in a folder in C:\tools.
That installation should provide everything you need to install Jekyll. However, on some systems we have had to also do these next two extra steps, which I recommend anyway. First, close the Command Prompt and open it again as an administrator.

Install MSYS2. This provides extra tools required for Jekyll's native extensions. To do this, run choco install msys2. (More details here.) Again, close the Command Prompt and open it again as an administrator.
Run the RIDK installer. Still more tools for native extensions. enter ridk install and at the prompts choose the default option to run options 1, 2 and 3 at once.


Again, close the Command Prompt and open it again as an administrator.


Install Jekyll. Run gem install jekyll. (You can run this command from any folder, since it installs Jekyll globally.)


Install Bundler. Bundler makes sure that, when you run Jekyll, you're running it with the correct gems. Run gem install bundler. (You can run this command from any folder, since it installs Bundler globally.)


Upgrading Ruby

New versions of Ruby do add important new features. For instance, we used to rely on Ruby 2.3, but Ruby 2.4 will properly downcase non-ASCII characters, which is important, and 2.3 couldn't do. For example, a heading like # Équilibre should get a lowercase ID, like <h1 id="équilibre">Équilibre</h1>, but Ruby 2.3 will give you <h1 id="Équilibre">Équilibre</h1>, which will break or render invalid links to #équilibre in case-sensitive systems (e.g. EpubCheck). This can also be a real pain when you're working with team members using Ruby 2.4 or later.
If you want to try upgrading Ruby you can run:
choco upgrade ruby

or to install a specific version of Ruby, for example:
choco install ruby --version 2.4.1.1 -y

The list of available versions is here.
If you upgrade, Chocolatey will add the new Ruby version to your PATH, but it will not remove the old version. This is bad: do not leave old versions of Ruby in your PATH, or at least make sure you reinstall your gems in your new Ruby version!
If you have Ruby 2.3 and upgrade to, say, Ruby 2.4.1, the gems you've been using will still be installed in Ruby 2.3.3 in C:\tools\Ruby23\bin. If you don't reinstall the gems (i.e. run bundle install in a project with a Gemfile), so that they exist in C:\tools\Ruby24\bin, and C:\tools\Ruby23\bin is still in your PATH, your computer will find the old, Ruby 2.3 gems and use them. The gems in C:\tools\Ruby23\bin will use Ruby 2.3. You will think you're using Ruby 2.4, but your gems will be using Ruby 2.3. You will be very confused, and you will lose several hours of your life to this mystery as I have.
The safe option is to edit your PATH to remove C:\tools\Ruby23\bin. That way, when you run Jekyll, you'll get an error telling you gems are missing, and that'll remind you to install them again.