Using Jekyll + Github Pages to build a blog

Why Jekyll and Github Pages

Jekyll is an static site generator, it is simple to use with YAML front matter. It is quite convenient to blog with markdown and Jekyll supports it build-in. Github Pages provide the space to host the website for free. Both of them are well-documented, and works well with each other. One thing that makes they works well but not perfect is that although Github Pages can generate the website using Jekyll but as it generates in safe mode, it does not support Jekyll plugin. However, the good news is we can generate the site locally and then push it to Github. It sounds like not convenient but we can write a bash script to do so automatically in one step. We will talk about it later.

Preparations

1. Know YAML front matter is something you can put at the front of a script and it can automatically
   • have part of the layout and tags you defined before
   • define variables (Liquid)
2. If you don’t know HMTL, CSS or JavaScript, you would better check out W3School and at least know the basic of them.
3. Be able to using git commands, if not please check Git tutorial or search on Google. You could use a desktop version instead of command lines, but I think it’s better to try comment line once because it may help you to have a better understanding of how it works.

Set up repository

Following the steps on Github Pages to initiate the repository. Caution: If you are building user/organisation pages, please use master branch, if you are building project pages, please use gh-pages instead.

Install and Initiate

Steps are shown here.

After installation, to initiate a basic theme Jekyll website at current folder, simply run

1
2

Jekyll new .
git init

If you have a error says the directory is not empty, just move all files to other directory and move them back after initiation.

Running Jekyll and Test Websites Locally

If you use bundler, you need to use bundle exec jekyll server or bundle exec jekyll serve.
For those who don’t, please use jekyll server or jekyll serve.

Leave command window as it is running and then open your browser and navigate to http://localhost:4000 and you can see your site locally.

Configuring

_config.yml file

_config.yml contains settings for the website, check out details at the official website here.

Host your website using custom domain

• you need to buy a domain from a domain registrar, like Godaddy.
• add a CNAME file which contains your custom domain name in the root of your repository.
• If your custom domain is a subdomain (like www.pwzxxm.com or blog.pwzxxm.com), then you need to add a CNAME record in your domain provider or DNS server provider if you are using custom DNS service.
• If your domain is an apex domain (only have one dot in your custom domain), you need to set up A, ALIAS or ANAME records. Add 192.30.252.153 and 192.30.252.154 to your records.
• Find more details

Pagination

There are two basic scripts can do pagination on Jekyll official documentation. However, I found this pagination from Timble which is awesome.

Multi-language site

Check out Jekyll Multi Language Plugin.

Build the site locally if you use plugins

The problem is Github build Jekyll websites in safe mode so the plugin won’t work. However, we can create a ‘dummy’ repository to generate the site first and then move the content in _site folder to the original repository.

1. generate the site locally using bundle exec jekyll serve build or jekyll build in the ‘dummy’ repository.
2. copy all files to the actual repository excludes README.md.
3. cut the files under _site folders to the root path of the repository.
4. touch .nojekyll to disable github to generate the site
5. commit all changes.

Here is a bash script:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

#!/bin/bash

comment="$1"
push_commit="git commit -a -m '$comment'"

# commit and push changes
eval 'cd ~/git/local'  # modify PATH here
eval 'bundle exec jekyll build'
eval 'git add .'
eval $push_commit
eval 'git push --all origin'

# copy remove in pwzxxm.github.io
eval 'cd ~/git/PwzXxm.github.io' # modify PATH here
eval 'cp ./README.md ~/git/' # modify where you want to temporally put the README.md
eval 'rm -rf ./*'
eval 'cp -r ~/git/local/* ./' # modify PATH here
eval 'cp -r _site/* ./'
eval 'rm -rf _site/*'
eval 'cp ~/git/README.md ./' # put the file back
eval 'touch .nojekyll'

# commit and push changes
eval 'git add .'
eval $push_commit
eval 'git push --all origin'
echo "Done"

To use it, simply copy it to a yourchoice.sh file, change the paths in the file and give it permission to run, and run it.

This Site

If you like the style or you want to know the codes behind it, just check out:

• Pwzxxm.github.io
• local site

You can grab and use any code from my site as you wish. However, the content of this site is copyright, if you want to use any posts please contact me.