12 Dec 2018 - garfbradaz - blog
The 1st how to for setting up the blog and tools needed to edit it. I’m a Windows fan (I love my Surface devices), but I’m also starting to appreciate Linux , so this is a perfect opportunity to set up my Surface Book to use Windows Subsystem for Linux, which allows you command line access to Linux. I’m assured this is not a virtual machine, but a syscall mapping between Windows and Linux itself, to actual Linux binaries themselves.
I’m going to provide the instructions on how I set up my Surface Book. You may want to tweak these to your needs.
NB: I originally posted this blog post December 2018 so if anything has changed or doesn’t work, let me know.
Windows Subsystem for linux needs setting up. If you have done this previously, then skip to code instructions
Use Powershell Windows Subsystem for Linux (WSL), make sure you Run as Administrator:
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
The prompt will ask you to restart your machine, so make sure you save anything before pressing Y:
Use the Windows Store to install your favourite Linux Distro. I chose Debian. More information here
Again if you have installed this previously, then jump to Jekyll.
I’m a great VSCode advocate, mainly from using .NET Core and C#. But I’m using TypeScript a little and using it more and more. I actually get a little sad face when I realise I need to use Visual Studio Enterprise for anything now (Usually because Razor support isn’t the best in Code, but improving).
I’m going to use Visual Studio Code to allow me to compose and edit markdown. Its the perfect editor because:
I will do a separate post on my Visual Code extension set up.
Download and install Code here.
As I mentioned previously, I installed Debian, so the instructions I’m giving are for Debian. More more information see here.
Firstly open a bash Window. I fired up Debian app I just installed.
Install dependencies for Ruby:
sudo apt-get install ruby-full build-essential
Now, I got the following error when I ran this on Debian:
Reading state information… Done E: Unable to locate package ruby-full E: Unable to locate package build-essential
Essentially the sources.lst is missing the deb-src links to the repository.
sudo nano /etc/apt/sources.list to edit the file and add the missing entries. Here is my file
sudo apt update.
Re-run step 2. If this works, move on.
Add the environment variables for gems for when bash is run interactively:
echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc echo 'export GEM_HOME=$HOME/gems' >> ~/.bashrc echo 'export PATH=$HOME/gems/bin:$PATH' >> ~/.bashrc source ~/.bashrc
Install Jekyll and bundler using
gem install jekyll bundler.
Confirm you have GCC and Make available:
gcc -v g++ -v make -v
You may already have Git for Windows set up on your Windows instance, but you will need to make sure Git is on WSL as well. Follow these instructions.
sudo apt install git
To validate it has worked, run
Set up standard email and username details:
git config --global user.email "email@example.com" git config --global user.name "your username"
As described here, need to set your line endings correctly.
git config --global core.autocrlf input
There are different steps that need taking when creating your repository. Firstly the repository names needs to be a specific format:
You can find your username my navigating (top right) click Your Avatar->Your profile. Example mine is garfbradaz:
So mine is garfbradaz.github.io.
You can select a Jekyll theme as well also. This is saved to the
_config.yml file in your repository. This can be changed at a later date.
Once the site is published, your repository name is your URL for your new site:
Run the following in WSL bash terminal to generate a key, replacing the email with yours that you use for Github:
ssh-keygen -t rsa -b 4096 -C <firstname.lastname@example.org>
Press Enter to accept the default directory, and add a pass phrase.
Add the SSH private key to ssh-agent so that you dont need to write the pass phrase each and every git commit:
Note: This is using ~ which is fine as we are within a Linux bash terminal.
Run the following to Print tne RSA key to the screen. Then using your mouse, copy to clipboard:
Navigate to github in your browser of choice.
Click on Your profile.
Click on SSH and GPG keys.
Click on button New SSH Key.
Give the key a meaningful title.
Paste RSA key.
Click on Add RSA key.
Firstly run Visual Studio Code.
Open a Terminal within Visual Studio code. One option for doing that is Menu->Terminal->New Terminal.
Then run bash.
Something important to note. After you run bash, you will be greeted with a directory prefixed with
/mnt/c. This means the drive is mounted and mapped to
C:\. You can prove this by doing a
ls. Look at all those familiar Windows files:
cd ~ && pwd isn’t your traditional home directory, so dont place any files in here you want Windows to access. This DOES NOT map to your Windows Home directory. If you edit this Linux Only Windows files, you will corrupt your Linux install.
Basically it is safe to use the
With that in mind, navigate to the folder you wish to clone your Jekyll repository, here is an example for mine (You do this in the same bash terminal you created in Visual Studio Code):
This is the following Windows directory:
Git clone into this directory:
git clone <your-repository-url> .
And because you are within Visual Studio Code, the files will appear straight away:
Now create a file called Gemfile and add the following (root of the directory):
source ‘https://rubygems.org’ gem ‘github-pages’, group: :jekyll_plugins
As you can see VSCode recognises up its a Gemfile and uses a nice Ruby icon.
Now create the dependencies. Within the bash terminal within Visual Studio code run:
Note: At this stage for Debian, I found there was an error installing nokogirl-1.8.5 dependencies.
I resolved this by running the following, then re-running
sudo apt-get install libpng-dev sudo apt-get install --reinstall zlibc zlib1g zlib1g-dev
If you want to amend the layout; add your own styles or navigation, then you need to check your themes repository for instructions on how to update (each may have different instructions).
The URL scheme for the repositories is:
So mine is:
Update your title and description for your blog.
> title: Gareth Bradleys Blog > description: garfbradaz new blog, hosted on github. Rambling about coding, running and > any other of my ramblings.
After you have proof read it and checked obviously. The beauty of Jekyll is you to publish your blog, you just use the git skills you (may) already have, so run the following in bash while in your repository where your
.git folder is:
git add . git commit -m "Start of life for my awesome blog - Arise!" git push origin
I will talk about How to Add Google analytics and How to publish your first post all in Visual Studio Code.
I haven’t written this blog post without help. I would like to shout out to the following blogs and documentation for assisting me: