Create a blog under GitHub Pages using Jekyll

Yizhou Wang   July 22, 2018  


Blogs are very useful for Ph.D.s to show some innovative ideas, technical tutorials, and some interesting stories. Create a blog under the GitHub Pages is really easy by introducing some static site generator like “Jekyll”. In this post, I will guide you to create a blog page on your GitHub website using Jekyll.

Start creating your blog from Poole

Jekyll is a static site generator, an open-source tool for creating simple yet powerful websites of all shapes and sizes. Poole is the butler for Jekyll. It provides a clear and concise foundational setup for any Jekyll site.

Here, I assume you have set up a GitHub Page under a GitHub repository <username>.github.io. You can refer to GitHub Pages tutorial to create your personal website. I downloaded a website template from html5up and you can also find many great templates there.

Clone from Poole GitHub repository:

git clone https://github.com/poole/poole

Create a blog repository on GitHub

Now, we are going to create a blog using Poole at https://<username>.github.io/blog/.

  1. Create a new repository on GitHub named blog.
  2. Remove original remote from Poole:
cd poole
git remote -v 		# View current remotes
git remote rm origin 	# Remove remote
  1. Add the remote Github repository blog:
git remote add origin <REMOTE_URL>

Set basic configurations

Basic configurations are written in the file _config.yml. Here is my settings:

# Setup
title:               Your Blog Name
tagline:             
url:                 http://<username>.github.io/blog
paginate:            10
baseurl:             "/blog"
paginate_path:       "/page:num"

baseurl can be set as any sub-URL that you want your blog running at.

Running Jekyll on your local machine

Install Jekyll on your machine using gem:

gem install jekyll

Run Jekyll server on your machine:

cd poole
jekyll serve

You will get something in the terminal like following:

Configuration file: <some_dir>/poole/_config.yml
            Source: <some_dir>/poole
       Destination: <some_dir>/poole/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
                    done in 1.071 seconds.
 Auto-regeneration: enabled for '<some_dir>/poole'
    Server address: http://127.0.0.1:4000/blog/
  Server running... press ctrl-c to stop.

Now, you can visit your blog at http://127.0.0.1:4000/blog/.

Push changes to gh-pages branch

Then, you need to push the changes to the GitHub repository blog. In order to show the blog at https://<username>.github.io/blog, you need to push all changes to gh-pages branch.

Create a new branch named gh-pages:

cd poole
git checkout -b gh-pages

Push the changes to the repository:

git add .
git commit -m "<some commits>"
git push

References

  1. https://jekyllrb.com/docs/home/
  2. http://romantsegelskyi.github.io/blog/2015/07/26/personal-page-blog/

jekyll  blog