Build Your Blog on GitHub with Jekyll

The three stages when you write a blog:

1.You uses an existed blog system such as Blogger or WordPress.

2.Due to limitations of the public blog system, you uses a third party blog system and put it on your own space or on a public cloud, such as GD-cms on GAE.

3.You want to write the blog locally with full control, and also let other website manages the backup.

This article teaches you how to build a blog on GitHub with jekyll.

##Table of Contents   Git and GitHub
  jekyll
  jekyll-bootstrap
  Important Issues

###<- Git and GitHub

Git is a distributed reversion control system. GitHub is a google code like system which can host your code and enable collaborative development. A lot of popular open source projects are hosted on GitHub, such as Bootstrap/Redis/jQuery.

1.Install Git and connect it with your GitHub account

Register an account on GitHub, download msysgit for windows. After a long time configuration, open the Git Bash and input:

git config --global user.name "your username"
git config --global user.email "username@email.com"

The username and email must match your GitHub account.

In order to create a SSH Public Keys, you need input:

ssh-keygen -t rsa -C "username@email.com"

After this, you will find the following information:

Generating public/private rsa key pair.
Enter file in which to save the key (/c/Users/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:

Omit the file path and enter your password twice.

Your identification has been saved in /c/Users/.ssh/id_rsa.
Your public key has been saved in /c/Users/.ssh/id_rsa.pub.

Find the file and open it, copy the key to your GitHub account setting, SSH Public Keys part.

2.Some common Git operations

Clone remote repository to your computer:

git clone git@github.com:accountname/reponame.git
cd reponame

Add update to a remote repository directly:

git init
touch README
git add README
git commit -m "first commit"
git remote add origin git@github.com:accountname/reponame.git
git push origin master

Change current repository (already in GitHub) locally and update to remote:

git command
git commit -m "content"
git push origin master

Other common commands:

add        Add file contents to the index  
clone      Clone a repository into a new directory  
commit     Record changes to the repository   
init       Create an empty git repository or reinitialize an existing one   
mv         Move or rename a file, a directory, or a symlink  
pull       Fetch from and merge with another repository or a local branch  
push       Update remote refs along with associated objects  
rm         Remove files from the working tree and from the index  
status     Show the working tree status  

3.Delete history commit

In your repo, suppose you want to delete a commit, find a commit later than this commit say a6901b3feq.

git rebase -i a6901b3feq

An editor will pop up and show a list of commits after this commit. Simply delete the commit you want and save the document.

git push origin master -f

###<- jekyll

jekyll is a simple, blog-aware, static site generator perfect for personal, project, or organization sites.

1.Install ruby and jekyll on windows machine

Download and install RubyInstaller for Window. Select "Add Ruby executables to your PATH" to add ruby to your system environmental variable when you installs the program. After the installation, input ruby --version in cmd to check whether ruby works.

Install DevKit and input the command in cmd:

cd E:\DevKit 
ruby dk.rb init 
ruby dk.rb install

Then you can install related package, input the command in cmd:

gem install jekyll

###<- jekyll-bootstrap

jekyll-bootstrap is a full blog scaffold for jekyll based blogs. Log into your GitHub account, create a new repository with project name: "accountname.github.com". Please note this repository must have the same name as your account.

1.Clone jekyll-boostrap

git clone https://github.com/plusjade/jekyll-bootstrap.git yourname.github.com
cd yourname.github.com
git remote set-url origin git@github.com:yourname/yourname.github.com.git

Then you can input jekyll serve, and check the blog content at localhost:4000. Note jekyll serve may give rise to an error. You can solve the issue as following:

gem uninstall jekyll
gem install jekyll --version "=1.4.2"

2.Structure of jekyll-bootstrap

_config.yml

this file stores the configuration of the blog. We can set name, email, github, twitter account, comments, analytics in this file.

_layouts

this folder stores the templates such as default, post, page file.

_posts

this folder stores the content of blog, file name follows the format:year-month-day-title.markup

_include

this folder stores the theme templates of blog.

_site

this folder stores the temporary local blog.

index.html

this file stores the main page of this blog.

assets

this folder stores the css/js file each theme uses.

###<- Important Issues

1.Change Theme

You can choose the theme and watch the theme at website. Select the theme, click the Install Theme button. I choose the-program theme, input the following command:

rake theme:install git="https://github.com/dhulihan/the-program.git"
rake theme:switch name="the-program"

2.Comments

I use disqus. You can register a disqus account and set the shortname related to your account in the _config.yml file:

  comments :
    provider : disqus
    disqus :
      short_name : XXXXX

3.New domain

First, you need to buy your domain. I buy a domain "itgeekworkhard.com" from Godaddy. Second, you need to create a new file CNAME with content itgeekworkhard.com in the project root folder. Note the file does not have any suffix. Third, in Godaddy, set domain pointing to IP 192.30.252.153. Then, set the value of production_url in _config.yml to your domain.

4.Figure

Define the variable img_url: /assets/images in file _config.yml, and use ![]({{ site.img_url }}/picture.jpg) to insert figures.

5.Blog Analytics

I use google analytics. You can register a google analytics account and set the tracking_id related to your account in the _config.yml file:

analytics :
    provider : google 
    google : 
        tracking_id : XXXXX

6.Pagination

set paginate: number in the _config.yml file. Number is the number of posts per page. Note there is NO indentation before paginate. For more information, you can check jekyll paginate.

Published: December 24 2013

blog comments powered by Disqus