Jean-Louis Mbaka Computer Scientist, Software Engineer, and IT Manager

How I created my first blog powered by Jekyll, Github, and Lanyon

Forewords

I have finally decided to make the big jump and start a blog. Years ago, I created a Wordpress blog but I ended up never posting anything on it. I will take the plunge for real this time, head first.

This will be a blog about my technical interests and adventures, and my projects. More about this blog can be found on the About page.

Introduction

In this post, I will be walking you through the steps that I took to get my first blog running. It is powered by Jekyll, a static site generator. I did not want to start from scratch so I used Lanyon, a Poole based template to quickly hit the ground running. I will be hosting this blog on GitHub Pages which was the natural choice for me because I host the majority of my development projects on GitHub.

Content

Before You Get Started

In order to complete this journey, we will need a GitHub account and some basic knownledge of how GitHub works. However if you have no prior knowledge of GitHub, it is easy to sign up and GitHub provides an extensive documentention on getting started.

Create a GitHub Repository

I begun my journey by creating a new Git repository with the name <username>.github.io where <username> is your GitHub username. It is important that <username> in the repository name above matches your actual username, otherwise GitHub Pages will not work.

Since my username is jlmbaka, the repository I created is jlmbaka.github.io.

https://github.com/jlmbaka/jlmbaka.github.io.git

Download and install the required software

The next step was to install and get Jekyll working on my PC. Below are the steps I followed to download and install Jekyll and its requirements on my Windows 8 machine.

Ruby

Download and install ruby from rubyinstaller.

Ruby Development Kit

Download and unpack Ruby DevKit from rubyinstaller into your choosen directory.

Open a Command prompt with Ruby, then navigate to the directory in which you unpacked the DevKit at the previous step (I unpacked mine in C:\RubyDevKit) and run the following two commands one after the other to install the DevKit:

$ ruby dk.rb init
$ ruby dk.rb install

Bundler

Bundler is a package manager for Ruby. It eases the pain of installing Ruby software. Install Bundler by running the following command from the ruby command line:

$ gem install bundler

Jekyll

In your site root directory (I named mine jlmbaka.github.io after the name of my repository), create a file called GemFile and add the following lines to it:

source 'https://rubygems.org'
gem 'github-pages'

After that, simply run bundle install to launch the installation process. This might take a while to finish, therefore be patient. Once the command returns, you can verify that Jekyll was installed correctly by running the following command (it checks the version of your installation):

$ jekyll --version

Poole

Download poole or lanyon templates from their respective GitHub repository and unpack the files into your root directory.

Run Jekyll

Open a console, cd into your root directory, and run the following command:

$ bundle exec jekyll serve

Make sure that your system path is configured with Python 2. I ran into an error Failed to get header. (MentosError) when I first tried to run the following command with Python 3.4 as my default installation. I switched to python 2.7.6 and it worked perfectly. Keep the avove in mind, it will save you from the frustration I had to go through until I found a solution.

By default, Jekyll will serve the site at the following address http://localhost:4000/. Open a browser and navigate the link.

Customisations

I applied the following modifications to my blog in order to get it to its current form:

Archive Page

I added an archive page to the side bar of my blog. This page dynamically generates a lists all of posts on the website. I followed the instructions of Joshua Lande to achieve this.

You just need to create a file archive.md in your root directory and paste the code below into it. This gets automatically picked up and added by Jekyll into the side bar.

---
layout: page
title: Archive
---

## Blog Posts

{% for post in site.posts %}
* {{post.date | date_to_string}} &raquo; [{{post.title}}y]({{post.url}})
{% endfor %}

Google Analytics

I also enabled Google Analytics on my blog. This was pretty easy. Just sign up to Google Analytics and register your website. At the end of the process, you will obtain a tracking code to be embedded in your website.

<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-64732940-1', 'auto');
  ga('send', 'pageview');
</script>

Save the code above in the file _includes/google_analytics.html and modify the file _layouts/default.html to include the following line:

{% include google_analytics.html %}

Doing so adds the tracking code on each page of your site.

Disqus Comments

Next I added Disqus comments to my site. I registered with (Disqus)[www.disqus.com] and then signed up for their Engage platform in order to obtain the Universal Code to embedded into the website.

<div id="disqus_thread"></div>
<script type="text/javascript">
    /* * * CONFIGURATION VARIABLES * * */
    var disqus_shortname = 'jlmbaka';

    /* * * DON'T EDIT BELOW THIS LINE * * */
    (function() {
        var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
        dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
    })();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript" rel="nofollow">comments powered by Disqus.</a></noscript>

I saved the code above in the file _includes\disqus_comments.html and added the following line where you want it the comments to appear to the file _layouts\default.html. In order to enable comments on a given post, add comments: True to the YAML Front Matter. More on this (here)[https://help.disqus.com/customer/portal/articles/472138-jekyll-installation-instructions].:

<div id="disqus_thread"></div>
<script type="text/javascript">
    /* * * CONFIGURATION VARIABLES * * */
    var disqus_shortname = 'jlmbaka';

    /* * * DON'T EDIT BELOW THIS LINE * * */
    (function() {
        var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
        dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
    })();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript" rel="nofollow">comments powered by Disqus.</a></noscript>

Push the blog to GitHub Pages

I concluded by publishing my blog to the web using GitHub Pages to host the site. The commands I typed on the console from the root directory of the website to push my repository to GitHub are as follow:

$ git remote add origin https://github.com/jlmbaka/jlmbaka.github.io.git
$ git pull origin master
$ git push -u origin master

That's it, we now have a Jekyll powered blog hosted on GitHub Pages.