Many of the websites I contribute to, like the Veeam best practices or the Cloud Connect book, use a combination of Markdown for the content creation and Jekyll for the web publishing. Thanks to our Git repository, we can focus on our content, share it among our peers and have it published easily without worrying about learning any web technology.
However, one part that is missing in any local editor, Atom or Visual Studio Code or anything else, is the capability to show the content in the so-called wysiwyg (“what you see is what you get”) way. This is not usually a problem, since in most of the situations the preview capabilities of the editor are enough, but there are times when we may need to see the website as it will be once published, for example when we need to create the menu structure.
But there is a way to compile our Jekyll sites locally, and thanks to some tips from my colleague Chris Arceneaux, I learned how to do it on my Windows 10 laptop.
Enable the Windows Subsystem for Linux
First of all, we need to have the Windows Subsystem for Linux. To do so, open PowerShell as Administrator and run:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
Then, enable the Virtual Machine Platform optional feature. Open PowerShell as Administrator and run:
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Restart the computer.
Download the latest package of WSL2 Linux kernel update package for x64 machines:
https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi
Run the downloaded installer.
Open PowerShell and run this command to set WSL 2 as the default version when installing a new Linux distribution:
wsl --set-default-version 2
Open the Microsoft Store and select your favorite Linux distribution. They are available at the address:
I’m using Ubuntu 20.04 LTS:
When you start the distribution, you may get this error:
WslRegisterDistribution failed with error: 0xc03a001a Error: 0xc03a001a The requested operation could not be completed due to a virtual disk system limitation. Virtual hard disk files must be uncompressed and unencrypted and must not be sparse.
This can happen when the folder where the virtual disks are stored is compressed. To remove the compression, go to:
C:\Users\YourUsername\AppData\Local\Packages
and look for a folder with ubuntu on its name, like this:
Do you see those two opposing blue arrows? that’s the sign that compression is enabled. Open the folder properties and in the advanced section, uncheck “compression”. This time the installer should complete without issues:
Now you can use the linux subsystem every time you want, by just opening a command prompt and running the command wsl:
Install Jekyll via bash on Windows 10
Now that we have our linux subsystem, we can use it like a linux distribution. First, like in any Ubuntu machine, we update our repository lists and packages:
sudo apt-get update -y && sudo apt-get upgrade -y
Next, we install Ruby. To do this, let’s use a repository from BrightBox, which hosts optimized versions of Ruby for Ubuntu.
sudo apt-add-repository ppa:brightbox/ruby-ng
sudo apt-get update
sudo apt-get install ruby ruby-dev build-essential dh-autoreconf
Next, we update our Ruby gems:
sudo gem update
Then we install Jekyll:
sudo gem install jekyll bundler
Let’s check our Jekyll version:
jekyll -v
That’s it! We’re ready to start using Jekyll.
Compile locally our website
We use internally at Veeam Gitlab, where we autheticate via email addresses and ssh keys. So, we need an ssh key from our local machine. To make it, let’s run:
ssh-keygen -o -t rsa -C "your.email@example.com" -b 4096
The email address has to be the same registered in our gitlab profile.
ssh-keygen -o -t rsa -C "you.email@example.com" -b 4096
We then copy the public key of our key pair towards our clipboard using:
cat ~/.ssh/id_rsa.pub | clip.exe
By the way, isn’t it cool that we can mix both bash commands and windows command in WSL? Right here, I’m passing the content of the SSH public key to my windows clipboard, so I can then paste it and save it in the “SSH Keys” menu of my gitlab profile.
Then, we find out in Git Desktop (or another git manager we are using) what’s the local folder where the cloned copy of our website is stored. In my case is C:\Users\Microsoft\Documents\GitHub\veeamvcsp .
So, we have to change the current folder of our linux shell:
Then, we run:
bundle install
Note: if your install fails at the step of installing the “nokogiri” gem:
Run this command first, as there may be this library missing:
sudo apt-get install zlib1g-dev
The installation should now complete successfully:
Now, we generate a temporary version of the website on our computer, running the command:
bundle exec jekyll serve --incremental
We finally open a browser to the address listed at the end of the command, and here we go:
Our Jekyll website is there!