24 Dec 2016

Move blog to github

Author: derek0883@gmail.com

There are many advantage moving blog to github, it is free, maintain with git, programmer loves git, and it using Markdown language. Visit Using Jekyll as a static site generator with GitHub Pages for more information.

Setup blog home page on github

Github give every user a subdomain, the URL is username.github.io. you can create an empty git repository. read this for how to creat new repository. then clone to local. submit an “hello github webpage” to remote. Note: username is your accout name of github.

$ git clone https://github.com/username/username.github.io.git
Cloning into ...
warning: You appear to have cloned an empty repository.

$ cd username.github.io.git
$ echo "<h1> Hello github webpage </h1>" > index.html
$ git add index.html
$ git commit -a "add testing file"

$ git push origin master

Few minutes later, Open browser and access http://username.github.io, you should be able to see the webpage “Hello github webpage”.

Blog maintainer want to focus on blog content instead of webpage maintain. Github support Jekyll, Textile, Markdown

Jekyll template including some basic configuration, and CSS, javascript etc, it define the style of your home page. Before you install any template, you need setup local developing enviroment.

Setup local developing enviroment

You don’t want to push every change to github to check the webpage, you need to debug at local, make sure everything is ok, then push to github.

$ sudo apt install ruby ruby-dev ruby-bundler
$ sudo gem install jekyll bundler
$ sudo gem install kramdown rouge

Now at the same directory you just checked from github, start jekyll.

$ jekyll serve 

Open browser and access http://localhost:4000, you will see the webpage.

Jekyll Template

Before you install any template, please try to build your site from scratch, you will understand better how template works. Refer to Directory structure of Jekyll sites using gem-based themes for more detail information about template.

Create _config.yml file including following context.

  toc_levels: 1..2
highlighter: rouge
  - jekyll

Add a Gemfile including following context.

# A sample Gemfile
source "https://rubygems.org"

gem "jekyll"

All of your blog pages should be under _posts directory, and create 1st blog page under _posts.

$ mkdir _posts
$ touch _posts/2016-12-24-hello.md

Put following context in this file.

layout: post
title: "Move blog to github"

> Hello jekyll

Hello jekyll. 

layout: post tells Jekyll use post.html under _layouts directory to “process” this post.

$ mkdir _layouts
$ touch _layouts/post.html

The content of _layouts/post.html

    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
      <div id='content'>

        {{ content }}


Now you need a homepage, it will list each post by default. So change index.html

layout: default

<table class='post-list'>

{% for post in site.posts %}
      <th><a href='{{ post.url }}'>{{ post.title }}</a></th>
{% endfor %}


The for loop will list each post under _posts directory. It will use default.html under _layouts to “process” this homepage. So edit _layouts/default.html

    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
    <link rel="stylesheet" href="/stylesheets/syntax.css" type="text/css" media="screen" charset="utf-8"/>
      <div id='content'>

        {{ content }}


Now start jekyll.

$ bundle exec jekyll serve 

Open brower you should see the homepage, it will list each blog under _posts, and click the link, you will see the content of each blog.

You can commit those changes to github.

$ git add _posts/ _layouts/ _config.yml Gemfile
$ git commit -a "build 1st homepage from scratch"
$ git push origin master

Now you should know how Jekyll template works. You can find online template, and add to the site. e.g. add some CSS file, javascript file.

Your own domain name

You can use your own domain name, instead of username.github.io. you just need to create a file named “CNAME”. it contian your domain name. e.g. you have domain name www.mydomain.com.

$ echo "www.mydomain.com" > CNAME
$ git add CNAME
$ git commit -a "add www.mydomain.com"
$ git push origin master

Then go to your domain name management page, modify your domain name setting, create a CNAME entry point to username.github.io.