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.

Advertisements

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.

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.