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.

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

Introduction

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.

Top Mobile App Design Mistakes

Note: This is a summary of an article by Kent Mundle on Toptal.

With tons of app rolling out each week, it is unlikely that your app will get any attention at all. To help your app stand out, here are some insights from seasoned app designers.

Poor first impression

Apps with no instruction, bare apps that looks like it’s designed a decade ago. Before we even figure out how the app works, we will be so annoyed we return to the appstore to look for less confusing alternatives. Here are some reasons for the frustration.

Improper Onboarding

Tailor to the needs of your users. Many “on the go” apps make the mistake of having a very tedious onboarding process. Don’t waste your users’ time. Don’t hinder them from using your app. Think progressive disclosure.

App without purpose

Many apps don’t even serve a purpose. Instead of solving problems, they are designed to follow trends. Once the novelty wears off, they are removed by your users.

Have a clear purpose for your app, and tailor the experience as so. Avoid features that do not align with the purpose. Make your app useful.

Dismissing app context

Use cases help define the purpose of your app. Have clear use cases for your app. Design all your features around these few use cases.

Example: Uber is designed to be very minimal, and excels at being used for quickly. This fits the purpose of the app — to serve the users when they are out with their friends. The unobstructive interface design helps the app fulfill its purpose without distraction.

Disregarding the development budget

After you get a rough idea of how your app will look like, approach the developers for a budget. Your developers are the one doing the work, they should be the one giving the estimates.

If you run out of budget too early, you will end up cutting critical features. Pioritize which features you need the most. Act within budget.

Cramming in features

Many apps try to do too much at a time, turning the app into an ultimate swiss army knife. The overwhelming features list makes your app difficult to learn. The best strategy is to beginning with a few features, then test out new features in the future.

Overcomplicating app design

When a designer finds themselves adding things to make the design more appealing, chances are, these choice will just result in a very cluttered design.

Instead of designing additively, design reductively. This method is directed as much towards content, concept and function as it is aesthetics.

Aim to fit the required content without cluttering the screen. Don’t let the design get into the way of your content.

Instead of designing addictively, design reductively.

Under utilizing app beta testing

All designers test their apps in some way or another. Very often, the beta testing is done in house. But you need a fresh set of eyes to review your work. Send out an ad and work with a selected group of audience to iron out the details, find out what’s missing.

Anticipate that the testing will often take 8 weeks to do properly. Give the process enough time in order to collect the quality feedback that your app design needs.

And so?

The app design market is a battleground, designing adequate products is not enough. Hook your users from the beginning – communicate and demonstrate the value your app brings.

Most of these revolves around having a clear idea of what your application is about. So, refine and refine until absolutely nothing else can be taken away without the project falling apart.

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.