Migration to Jekyll

In the last post, we talked about migrating my blog from its current WordPress hosting to GitHub Pages.

From now on, the blog will be available at ongspxm.github.io. You can check out new content over there.


Blog migration to GitHub Pages

TL;DR I migrated my blog from WordPress to Jekyll to be hosted on GitHub Pages


I have long since had the idea of migrating to a blog maintained by a static site generator. This allows me to store my content in textual format, giving me more control over them.

Getting the theme ready

For GitHub Pages, the default static site generator that they use is the Jekyll generator. This is quite a full-fledged generator, complete with support for pages, blog posts, and plugins which can help extend the functionality of the site.

Starting with a minimalistic theme

I have seen many text-based blog theme used to good effect. With only text to work with, the design is very much typography based. But I would also like to give a slight developer, “hackish” feel to my blog, so I went on to JekyllThemes and selected this beautiful monospace theme by Micah Cowell.

Adding some design touches

The first impression on the theme is the lack of code highlighting. Considering that my posts contain quite a bit of code in it, it would be nice to have some sort of code highlight for easy readability.

This code highlight has two part to it. The first one will be a simple code that written in the post itself. The second type would be embed gists.

For embed code, Jekyll uses code highlighter that plays well with Pygment theme. Since Pygment is a rather well-established system, there are really many options we can go with. I went with a dark theme that quite nicely matches with the original theme code display.

The Jekyll theme that I started with made used of SASS to link together all the different stylesheets. I took advantage of that and linked the corresponding stylesheets to the main sheet. The organization of the source file made all of that easy work for me. (Kudos for the theme arrangement)

Adding all the features

One of the reasons why I chose WordPress before this is the ease of setup, where all the features are there. There is built in tag and categories system, comment systems, and analytics system to track page views. All these are not readily available in Jekyll. You have to do some work to implement them.

Tag and category system

The tag system in the theme has a manual system that requires you to key in the tags to generate the tag index page. But that is too much trouble for me, so I will go with the automated process.

I so went in search of a plugin to add automatic tagging system for Jekyll. In the end, I have decided to build upon Jekyll default tagging system and have a plugin that uses the jekyll plugin system to generate the tag index page.

I did something similar for the categories too. To have a more depth understand of how I did it, refer to the tutorial here.

Blog analytics

Google analytics can be embedded into any page. It tracks quite a lot of details. There is the IP address, the countries, the page visited, almost everything that you can find on the WordPress JetPack system. I have a tutorial here that details how to add Google Analytics to your Jekyll blog.

Comment system

WordPress has its own comment system where everything is stored in a mySQL database. But for the rest of the blogging world, the DisQus commenting system is used instead. It is possible to embed the Disqus comments into a Jekyll site too. After all, it is just another javascript file away. I have a tutorial here that details how to add Disqus comment to your Jekyll blog posts.

Importing the content

After the theme is ready, the next stage will be to import the content from my existing WordPress blog into the Jekyll theme. We first have to export the WordPress posts in the XML format. If you need help, you can refer to WordPress own help page.

Deciding on blog structure

Previously when I was using WordPress, I didn’t put in much effort into post organization. There are multiple categories for each post. There are different categories of posts, of which some are used just for a few posts.

After blogging for a while now, I recognize these problems and went ahead a drew up a set of simple organization for my posts.

Each post can only have one category, but can be given multiple tags to add further description to the post.

Extracting the posts

So for each post, there are a few metadata that needs to be included, the slug, date, tag and category. From the XML file, I will extract all these information into their separate files to represent one post each.

To automate this process I have written a script to do all these.

After the posts are generated, I check and update the posts’ information. Then I move everything into the _posts folder and run jekyll serve --watch. I check through all the posts to ensure that there aren’t any problems with the content.

The End?

This blog would probably be an ongoing project. After importing all the posts, there would certainly be more features and plugins that I would like to add to my blog, ability to attach gists, Imgur album, google drive files. All these will probably come into play in the future.

Adding Disqus Comments to Jekyll

TL;DR Adding Disqus comment system to Jekyll site.


Jekyll is great for static site content, but when it comes to dynamic content such as comments, we will have to turn to embed comment system, Disqus for help.


Disqus is an addon that powers discussion threads. For blogs, each discussion thread would represent a blog post, with all the comments under that particular thread.

Go on to Disqus and sign up for an account if you do not already have one. Create your site, add in your site details and all. This site object is where all your threads will be stored.

Login to your dashboard, and navigate to the embedded options there (Admin > Installing Disqus > Universal Code). Disqus provides extensive support for all sorts of platforms. But in our case, we will be using the more generic embed code version.

The code that you have will look something like this:

<div id="disqus_thread"></div>
< script>
var disqus_config = function () {
    this.page.url = PAGE_URL;
    this.page.identifier = PAGE_IDENTIFIER;

(function() {var d = document,s = d.createElement('script');s.src = '//ongspxm.disqus.com/embed.js';s.setAttribute('data-timestamp', +new Date());(d.head || d.body).appendChild(s);})();

How to use?

Think about where you want your comment thread to be placed in. For me, I would want my Disqus comments to only appear in posts. It does not make sense to have a comment thread appearing on the homepage.

With that in mind, we will be placing the Disqus embed code into our _post.html template in _layouts.

How does the code work? To identify which thread you want to load on that particular page, you define the thread’s id as page.identifier in disqus_config(). So what do we use as the page’s unique identifier? Looking at Jekyll documentation, we can see that page.id would be the ideal id for our Disqus thread.

Now make the appropriate changes to the embed code and paste it into wherever you want your comments to be displyed. Now paste the following code into _layouts/post.html:

<div id="disqus_thread"></div>
< script>
var disqus_config = function () {
    this.page.identifier = "{{ page.id }}";

(function() {var d = document,s = d.createElement('script');s.src = '//ongspxm.disqus.com/embed.js';s.setAttribute('data-timestamp', +new Date());(d.head || d.body).appendChild(s);})();

Finishing touches

The final feature that we will add in for this tutorial is the ability to disable comments. To do this we will make use of the front matter YAML that is included in each post.

We will create a new variable nocomment in the post’s front matter(accessible in post.nocomment). If it is not defined, the Disqus thread will be displayed. If the value of page.nocomment is set to true, then the thread will be hidden.

Wrap the disqus thread code with the following Liquid template tags:

{{ "{% unless page.nocomment " }}%}
<div id="disqus_thread"></div>
< script>
var disqus_config = function () {
    this.page.identifier = "{{ page.id }}";

(function() {var d = document,s = d.createElement('script');s.src = '//ongspxm.disqus.com/embed.js';s.setAttribute('data-timestamp', +new Date());(d.head || d.body).appendChild(s);})();
{{ "{% endunless " }}%}

The end

Using this technique of including snippets of code into your template, you can greatly extend the functionality of your site. Using this method, you can add in other forms of plugins such as chat and tweet display.

Adding Google analytics to Jekyll

TL;DR: Adding Google analytics to your jekyll site. Skip to tutorial


One of the reasons why I chose WordPress previously is because of the built-in analytics system provided by the JetPack addon. There is no built-in analytics package for Jekyll, but with some learning, we can make good use of Google analytics to provide all the site tracking that we need.

In this tutorial, you will be adding google analytics tracking to your template, and with a little magic, turn it into a very convenient feature in your theme that you can turn on and off easily with the help of Jekyll site config.

Getting started

First, you will have to get the embed code from the google analytics site. After signing up and creating your site, you will see the embed code section, go on and copy that.

If it is not on the main panel, the tracking code can be found in the following tab: Admin } Property } Tracking Info } Tracking Code

Embedding the code

Now we will have to insert that piece of code into a template that will be used in all the pages. If you use a ready made template, most of the template organization will probably include a header template where all the scripts and stylesheets are loaded. You can insert your code there.

If you cannot find any header template file. Create one. Now go on to the _includes folder of your site and create a file ganalytics.html. Paste in your embed code and make the appropriate changes to the identifier to let the server know which page is being visited. You should have something like this:

  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),

  ga('create', '&lt;unique tracking id&gt;', 'auto');
  ga('send', 'pageview');

Now the next part will be to embed this file into all the template that you would want google analytics to track. This will typically include all your post(post.html), page(page.html) and your default templates (default.html).

You should add in something like this somewhere along in the template, in the header.

{% include ganalytics.html %}

Finishing touches

If you inspect the code for google analytics closely. You will find that the only part of the code that is identifying where the traffic is tracking is the identification code. If we remove that part out and put in into the config, where it will be more accessible, this will make your theme more flexible and much easier to edit.

So now, we put in the google analytics identification into your config page, _config.yaml.

google_analytics = &quot;UA_123456_1&quot;

Then we will have to make some modifications to the ganalytics.html to include the identification value given in the site config page. Change your code so that the script source looks something like this:

  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),

  ga('create', '{{ site.google_analytics }}', 'auto');
  ga('send', 'pageview');

The end?

There isn’t much to do after this. After all, Google Analytics is supposed to be a all-in-one tool, which includes everything required for site and page tracking. All that is left to be done is to learn to use the google analytics panel well so that you can get the information that you need easily.

If you need any help on that, you can check out the official youtube channel for help.

Adding tags and categories to Jekyll

TL;DR Build upon Jekyll’s built-in tag and category tagging system, skip to tutorial

Note Source files are available in this gist


Jekyll is a very good static content generator in all rights and is a pretty good fit for blog posts in general. However, the core is missing a key feature: tags and categories.

Although Jekyll posts support the use of tags and categories, it is up to the theme to implement these features and display them in the layout. This is very annoying, especially when it comes to creating an index for all the tags and categories, since there is no simple way of getting the tag index.

The solution

This tutorial will help you add a generated tag index page to your blog. This page will include all the posts that are of a certain tag (or category), making your blog navigation easier.

This tutorial will focus on create the tag index page for your Jekyll blog. The idea is pretty much the same for categories.

During compilation, the generators that we created will be activated and will then generate the list of posts for the corresponding tag. Then for each tag, they will be parsed into the tag index template page, where the list of posts will be displayed along with the details.

Generating the tag index page

For this to work, there are a few things needs to be created. One, the generator itself. When all the information of the posts have been read into the system, the built in tag system will register the tags to each post in post.tag as a list. We will be creating a generator to create the index page, the plugin will be in the _plugins folder in the root directory as a ruby file.

The plugin will create a TagGenerator object that creates a new ‘TagIndex’ page for each of the existing tags. The TagIndex page uses a different template file(_layouts/tag_index.html). How the posts are displayed is defined in the template file later. This plugin file will reside in _plugins/_tag_gen.rb.

The content of the template file for the tag index will include a main for loop that loops through the list of posts, and print out the details of the post individually. Below is a simple example of a tag index page, with minimal details and styling. This template file will reside in _layout/tag_index.html.

And to add the finishing touches, we add the links to the tag index page to the posts themeselves. This will have to depend on how you define the permalink for your tags. For each tag, you just have to add link to the index page. For a simple list of tags separated by commas, you can add in something like this in your post template.

Testing it out

Now when you build your Jekyll site, and go on to the individual post page, you will be able to access the tag index page and see all the posts that are tagged with that particular tag.

What about categories then? Using the same idea, create your category generator and your category index page. Most of the changes would probably be just to rename the variables in the generator and index page. If you need help, you can view the appropriate files under _cat_gen.rb and cat_index.html under the gist to view the changes to make.

The End?

The Jekyll static site generator is actually very extensible and has support for a very extensive plugin system. In this tutorial, we have only used the generators, but if you interested in building more plugins for Jekyll, you can take a look at official plugin documentation.