Installing and Learning Jekyll and GitHub Pages
I have been talking about making a blog for all of my hobbies and projects for a very long time and here we are; I finally made the Thing!
So I thought for my first official post I’d post about actually creating the blog and getting up and running using GitHub Pages and Jekyll because I found it surprisingly difficult to find where to start - especially using windows.
Creating the skeleton using GitHub Pages
Barry Clark provided me with a great starting point with his article Build a Blog With Jekyll And GitHub Pages where he outlines how to get up and running as quickly as possible using GitHub pages to do all of the ‘hard stuff’ for you.
Using a mix of the two links above and a small amount of Googling I finally had a skeleton “Hello World!” version of this blog up on github pages. After some time of experimenting with the next few steps, I went ahead and made it a bit more pretty by implementing a theme I found on on the Jekyll Repo called Slim Pickins. Next up was to allow for offline/local editing.
Install a good editor
I’m currently using Notepad++ with a syntax highlighter called Markdown Syntax Highlighting for Notepad++ to edit my files. I have included the modified file that I actually used here
Installing GitHub
I have only briefly used git and github previously in a very superficial sense (only downloading zips of other’s projects) so I also needed to download, install and figure out GitHub to get my files locally. This just involved installing the program, logging in and cloning the repo containing the site to my local machine.
Installing Ruby and Jekyll
Julian Thilo has written a fantastic step-by-step guide to setting up Jekyll on Windows. Basically; Jekyll relies on the Ruby language to operate so the next step was installing Ruby and the Ruby Development Kit on my local machine.
A few notes and hiccups I had while installing:
- I first installed the 64-bit version of Ruby and the DevKit simply because that matches my system however I encountered a few issues while installing and a quick Google revealed that the 64-bit version actually doesn’t play nice with the other kids. So this was easily fixed - I uninstalled the 64-bit version and instead installed the 32-bit Ruby, I doubt a newbie like me would really be affected by the performance differences.
- I also for some reason attempted to install the DevKit in Program Files which is fine to unzip to but will not allow you to properly install. I then realised their recommendation was just for C:\RubyDevKit\
- I installed Python in the hopes of installing pygments but evidently that hasn’t quite worked out, I’ll put that on the to-fix list.
- Jekyll had a big list of errors when first trying
jekyll serve
so I used this fix from Stack Overflow to re-install a working version of hitimes
tl/dr: Quick and dirty ‘How to Install’:
- Install Notepad++
- Install Markdown Syntax Highlighting for Notepad++ by adding the given
userDefineLang.xml
to%APPDATA%\Notepad++\userDefineLang.xml
to enable Markdown syntax highlighting in Notepad++. - Install GitHub and clone the website directory to the local machine.
- Get Ruby for Windows, 32-bit works better with everything and ensure you select “Add Ruby executables to your PATH”.
- Get Ruby Development Kit for Windows (scroll down) - extract to
C:\RubyDevKit\
- Open command prompt.
cd C:\RubyDevKit\
ruby dk.rb init
ruby dk.rb install
- Install Bundler:
gem install bundler
- Go to the GitHub website directory (where the Gemfile is) and run
bundle install
and possiblybundle update
- Build the server with
jekyll serve --watch
, usebundle exec jekyll serve
if errors show up and also set the--drafts
flag if you want to include drafts.
Editing and Previewing
- Login to GitHub locally and ensure the appropriate repo is cloned to an appropriate local directory.
- Open command prompt and navigate to the root directory
cd Twulz.github.io
- Run
jekyll serve --watch
and wait for the messageServer running...
The--watch
flag ensures that when changes are made, the site will be updated automatically. - Open a browser and go to
http://localhost:4000/
to see the site. - Edit any required files.
- Refresh the browser to see the changes.
- When changes have been made, GitHub will show this so enter a summary and description.
- Click
Commit to Master
- Click
Sync
in the top right hand corner - The changes will now show up on the site at
twulz.github.io
Other useful notes:
- Posts won’t show up until the date(/time) has passed. This is possibly based on US time.
- Use
jekyll serve --watch
to build and display the site inlocalhost:4000
. Usejekyll serve --watch --drafts
to show posts in the_drafts
folder too.