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.

Prerequisite Chocolatey

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.

  choco install firefox
choco install [package]

and then

  choco uninstall firefox

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)

Lastly I do prefer this console emulator from the basic one on windows, find the GitHub repository here with install and usage instructions.

Installing Jekyll

Now with choco up and running with your console of choice open with administrative access we need to install ruby first.

  choco uninstall ruby -y

Restart your console with administrative access and install the gem bundler.

  gem install bundler

Now to install Jekyll, a ruby gem.

  gem install jekyll

You should now have Jekyll installed in your windows machine. To test this type :

  jekyll --version
gem list jekyll
gem update jekyll

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.

  //create new blog site
jekyll new MyBlogName
//navigate into that directory
cd MyBlogName
//build the site and preview on local host
bundle exec jekyll serve

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.

  //watch for changes and build regenerate automatically
jekyll build --watch
//start local host server
jekyll serve
//kill local host server
jekyll serve --detach

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.

Trouble Shooting

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.

Conclusion

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.