Its only fitting that I post on the development of my own blog and many of the troubles I encountered with its instalment on a windows machine. Easily, I could have saved myself all this trouble if I had just simply fired up a more compatible OS with ruby and Jekyll in a virtual box but I was too damned stubborn and determined to get it running on my windows machine. So it makes sense that I write up a troubleshooting guide on how to fix the most common errors I faced in hopes this would help solve the same issues anyone else is having with some extra alternative -much easier- methods on how to get a static blog running off your GitHub domain in no time.
You will need a windows package manager called chocolatey that will install ruby, gems and other packages. It operates very similar to any linux command line based machine using “apt-get”. To install this open a command prompt with administrative privileges and paste in the following command.
@powershell -NoProfile -ExecutionPolicy unrestricted -Command “iex ((new-object net.webclient).DownloadString(‘https://chocolatey.org/install.ps1’))” && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin
To test that you have chocolatey up and running why dont we install try to something.
That should successfully install and uninstall firefox using choco. Too view the full list of other packages available click here and here for a list of choco commands. (“choco –help” will bring up useful information on how to operate choco)
Now with choco up and running with your console of choice open with administrative access we need to install ruby first.
Restart your console with administrative access and install the gem bundler.
Now to install Jekyll, a ruby gem.
You should now have Jekyll installed in your windows machine. To test this type :
and you should receive a version of jekyll 3.X.X
Build your first blog
To build and publish your first blog it is quite simple. Inside a directory you wish to store your new blog type the following commands.
Now your empty folder will have all the necessary files required by jekyll and can be viewed by navigating to your localhost port in any web browser.
When it comes to development you should test changes at you local machine before pushing any updates to GitHub.
With that all out of the way you should now be able to generate new static websites whenever you like and hopefully youve come to appreciate how useful a tool like choco an be on a windows machine.
Now the biggest problem with running this on windows will be the SSL certificate being outdated on ruby so you will most likely have issues with installing any ruby gems. To solve this all you have to do is update ruby gem yourself, here is a helpful guide on how to do exactly that.
Running on GitHub
To run your static blog live for free on your main github account you will need to create a repository with this exact naming format: YOURUSERNAME.github.io . Push all of your generated files into this repository and it should automatically compile every time you push a new change. To view your blog navigate to YOURUSERNAME.github.io on any browser. Note that GitHub pages will have difficulties compiling to private repositories so i suggest you give this a quick read if you plan on having sensitive information in the back end.
Static Vs Dynamic DOM
Recall that Jekyll is a static website generator and that means once it has compiled it will NOT natively change any elements in the DOM on its own. Dont try to program this as if it was a HTML website using CSS, you will need to learn the kramdown Syntax. However if you do wish to manipulate the DOM at run time this can be done using Js or Jquery.
There are a few Prerequisite that you need to watch out for before installing Jekyll but once you have it up and running it becomes easy to understand the structural architecture its built upon. I recommend you download one of the themes for a quick style so you can get blogging right away. You can take things a step further by redirecting github.io to your own domain name like i have or set up a google-analytics account to mine traffic data. Head on over to codeacademy for a step by step walkthrough on how to install and configure Jekyll for github.