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.

Advertisements

Blog migration to GitHub Pages

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

Introduction

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.

Introduction

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?

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);})();
</script>

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);})();
</script>

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);})();
</script>
{{ "{% 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

Introduction

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:

  (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','https://www.google-analytics.com/analytics.js','ga');

  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:

  (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','https://www.google-analytics.com/analytics.js','ga');

  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.

Redirecting GitHub Page to a custom domain

Note: This tutorial requires you to have a domain. If you don’t already have one, you might not be able to really try this out for yourself. But still, this tutorial will make a good read 🙂

TLDR: Skip the explanation and go straight to the steps

The reason why I chose Github Pages is because of my extensive usuage of Github in general for project hosting. Using GitHub Pages fits into my workflow. Have the content ready, push it to GitHub, and it will be deployed to GitHub Pages.

Plus, using GitHub Pages means that you can take advantage of the Jekyll generator. You can focus on your content, push it to GitHub, and it will be “compiled” automatically.

I have plans to migrate my blog to my github account. If everything goes well, you can expect a tutorial on how to setup a blog on there, complete with google analytics and all that.

Setting up a page on github

Each account on GitHub will be allowed one subdomain in the following format: .github.io. If you already have your content ready on that repository, you can skip this section. If you have no idea what I am talking about, read on.

Create a new repository, then go on to the “settings” tabs of your repository.

Note: Your new repository must have the following name: [username].github.io, where [username] is your GitHub handler.

Scroll all the way down to the section where it says “GitHub Pages”. Go on and “launch automatic page generator”. This generator lets you edit the information to your page. Choose a nice layout and save the changes.

What you have just done is to create a new branch master in your respository and populate it with the generated page. If you go on and see the files available (in the “code” tab), you will see the index.html sitting there, waiting to be shown to the world.

Basics of DNS settings

If covered in detail, this section can take a whole posts by itself. Instead, I am going to just cover a simple version of it, covering what we will be using in this post.

Types of domains

Before that, let’s cover the few types of domain that GitHub supports. The first type would be apex domain. This is the “main” domain. Examples of such domains would be test.com, example.com, google.com. These are one level below the top-level domain (.com, .org, etc).

Then we have subdomains. These are one level down the apex domains, and are usually used to split up your sites into different parts. Examples would include blog.test.com, ongspxm.github.io (see GitHub uses subdomains too).

DNS Record types

There are a few different types of DNS records. These records will point to different resources, then your request will be passed from one resource to another and finally be resolved to an IP address.

Here, I cover the A record and CNAME record, which is used in pointing your domain to a certain resource online. No idea what I am talking about? Read on.

A Record

An A (address) record directs the hostname to a certain IP address. For example, you could have test.com point to your home computer and serve files out of there. Let’s assume your home computer has the IP address 192.168.0.1. Your record will look something like this:

Name/Host   Type    Value
test.com.   A       192.168.0.1

Note that in the host section, there is a trailing .. It refers to the top level domain. But for the IP address, there isn’t any top level domain to resolve, hence, there is no need for the trailing ..

CNAME Record

The second type of record CNAME (canonical name), is also known as the alias. This allows you to point different subdomains to different parts of the web. Unlike the A record, the CNAME need not be an IP address, it can point to a domain or a subdomain.

The request will follow the resource that the records points to and continue to resolve the request from there.

Name/Host   Type    Value
www         CNAME   @

This CNAME record redirects the www subdomain to the apex domain (the @ symbol is a shortcut many hosting use to refer to the apex domain). So when you go to http://www.example.com, it will be resolved to example.com.

Changing the settings

Go your GitHub respository, go to “Settings > GitHub Pages”. Let’s say your domain is example.com. Change your “Custom Domain” to http://www.example.com.

Now login to your GoDaddy account, and navigate to “Domains > Manage DNS”. You will be brought to a table of records. There will be some of the default record there already. You will see a few A records, some CNAME records, and some MX and NS records (not important for now).

Create a new CNAME record with www as the name. Now put in your github pages link as the value. So your record will look something like this.

Host/Name   Type    Value
www         CNAME   <username>.github.io

Note: If you already have a www CNAME record, you can edit it to point to your GitHub Page.

Check if it is working

For those who are used to setting up network, working with DNS, you will probably be familiar with “dig” (DNS information groper). For those of you starting out, there is an online version that you can use to check your settings.

Now go onto the page and under the “domain name” textfield, enter your www subdomain (eg. http://www.example.com). Perform the query and wait for a while. If everything works, you will see a list of addresses, similiar to the following list:

<username>.github.io.
github.map.fastly.net.
prod.github.map.fastlylb.net.
151.101.100.133

If you want a more verbose query with more information you can choose to uncheck the “short” checkbox.

What does the list mean? When you visit http://www.example.com, it resolves to .github.io. That is what the first line represent. So the list is basically a “path” of what the request went through, finally arriving at GitHub Page’s IP address: 151.101.100.133.

Try this instead

What about apex domain? Didn’t you mention it before? What about the A record that you mention earlier?

Run the verbose DIG query (without the “short” selected) on your domain. If everything is working well, you will notice the last line of the records (the end of the “path”) is actually an A record.

What this actually means is that when everything is finally resolved, the final IP address that your http://www.example.com points to is that 151.101.100.133.

What if you want your example.com to point to an IP address too? What if you want to setup your github pages with an apex domain?

Changes these settings

First go over to GoDaddy DNS management portal. Add 2 A entries into the table. Link them to 192.30.252.153 and 192.30.252.154 respectively. These are the IP addresses for GitHub Pages server. Your table will now look something like this:

Name/Host   Type    Value
@           A       192.30.252.153
@           A       192.30.252.154

The @ symbol represent the apex domain (eg. example.com), without any subdomain. The following setting will redirect the apex domain (example.com) to your GitHub Page.

If you want to resolve a subdomain to your GitHub page, you can do so by changing the “Name/Host” to whatever subdomain you want. (changing it to blog will result in blog.example.com resolving to your GitHub page.

If you need help, you can refer to the official help page.

Checking that it works

Use the DIG tool that I told you just down. Query your own domain, you should see a list like this:

192.30.252.153
192.30.252.154

These IP addresses represent the A records that your domain has been pointed to.

Done?

There are many different kind of records that DNS server use to help resolve different requests. This posts only cover a few of those. If you want to learn more you can take a look here to see what’s the difference between the varying types of records.

GoDaddy uses A records, but other hosting platforms might use different kinds of DNS records such as ALIAS or ANAME. To learn more about setting up GitHub Pages on those hosting sites, you can take a look at GitHub’s own help page.

Introducing tumblr pbot

Journaling can be difficult sometimes, you need to have your book with you, you are not sure where to start, you get distracted. These are problems faced by many of us.

Tumblr pBot helps you get started on your journaling in as little steps as possible. Just start typing and send it, and up or goes onto tumblr.

Want a private journal, no problem, just make your tumblr page private, and nobody will be able to access your private thoughts.

Want to review your entries? Since everything is uploaded onto tumblr, you can make use of tumblr post management system to review and read through all your entries.

Want to categorize your entries? Use tags. Tumblr’s tagging system is supported in the pBot. Simply add in the tags at the end of your posts and it will be immediately uploaded with tags attached.

Don’t know how to start? Even better. Using telecom’s text messaging interface makes it feels like you are typing to a friend, making it easier to pour out all you have to say.

Getting distracted from writing? pBot is as minimal as it gets, you can now focus on what you are writing. Since its so accessible, you can get in, pour out your thoughts, and get back to whatever you are doing.

Try it out now. Or visit the bot page.