Setup your Jekyll blog locally on Windows 10

 

~ 3 min read.

Setting up Jekyl is pretty much straight forward, but if you are on Windows and have no background with Ruby it might be somewhat confusing, so here we will be able to see the steps required to: setup, build and run your blog on Windows 10 machine.

Install Jekyll

Jekyll is a framework written in Ruby, so naturally you will need to have Ruby installed on your Windows machine. Jekyll in it’s official documentation offers the steps and prerequisites needed, but since I am not a fan of downloading and installing executables I will use Chocolatey, so it can do it for me :grin:

Install Ruby

Currently Ruby 2.6.* is not stable for Windows, since lots of gems are not available on Windows platform yet, thus the reason for specifying the version.

choco install ruby --version 2.5.3.101 -y

Install Chocolatey

If you don’t have Chocolatey installed check this link, or run the script below in Powershell:

Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

or the one below if you prefer CMD:

@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"

NOTE: Whatever shell you decide to use, please make sure to run it in admin mode (right click select: “Run as administrator”).

Run refreshenv. This setup is required since your opened shell might not be aware of system environment changes regarding Ruby path which you need in order to run Ruby commands.

Install MSYS2

Next we need MSYS2 which is a replacement for Ruby DevKit which was used in earlier versions. Run the command below to install:

ridk install

There will be couple of steps to go through:

Menu

We got the menu with three options and we will chose the number "3". Setup will detect that we don't have the base installation so it will download it and install it.

MSYS2 Setup

Next we will see the popup window of MSYS2 installation wizard.

MSYS2 Installation path

I recommend to use the default path. When I changed the path to: "Program Files", MSYS2 didn't worked correctly!

Finish install

The install will take a bit, and finally on finish screen just uncheck the checkbox about running MSYS2.

Chocolatey will patiently wait for MSYS2 install to finish, and after you close the installation popup it will continue, this will also take a minute or two at the end you should be offered the same three option as on the start. Press ENTER and finish the installation.

Install Jekyll

Now that we have Ruby and DevKit installed we can install Jekyll. Run the command below:

gem install jekyll bundler

To be sure that Jekyll has been installed correctly run:

jekyll -v

your should get a result similar to:

jekyll 3.8.5 (version number might differ)

if everything is installed correctly.

Create your blog

Writing how to create a blog using Jekyll is out of the scope of this post and you can read the excellent official Jekyll tutorial which I highly encourage, or if you prefer to jump right to running the blog then you can clone/download the code from this repo.

Build and Run your blog

If you followed the official tutorial then this step is already known to you and I will like to thank you for taking the time to read this post, if you downloaded the source then open the prompt (CMD or PowerShell) from the root folder of you blog and run the command:

bundle install

Check the documentation and other Bundler commands.

After the bundler has finished with building everything run:

bundle exec jekyll serve

Note: All changes will be auto-updated except for changes to: “_config.yml”, for them you will need to stop Jekyll ctrl + c and re-run the last command.

Running in production mode

The documentation says run:

JEKYLL_ENV=production bundle exec jekyll serve

but on Windows there’s no way to run this command, and setting environment variable doesn’t help also. I tried running the command with git bash, but it didn’t help. I tried many of workarounds I found on Google, but none worked for me :cry: So if you end up with the same issues you will have to tweak out directives like this if you want to seed them while in development:

{% if jekyll.environment == "production" %}
   {% include disqus.html %}
{% endif %}

Conclusion

That’s it, taking into consideration that I am not a front-end developer Jekyll provided me with many shortcuts (you can setup a basic blog without writing a line of JavaScript) and I find it one of the simplest frameworks I encountered plus there is a plethora of themes on Github that you can use, or modify to your liking if you don’t mind diving a bit deeper into Jekyll mechanics.