Jekyll and gh-pages

EDIT: After writing the following article, I found out there is a free course available for creating and managing your GitHub pages (gh-pages):
https://lab.github.com/githubtraining/github-pages

The lab.github platform seems quite nice, it is never too late to browse all these courses!

That said, Find below my original article.

---

Jekyll and gh-pages

GitHub allows you to use your repository as a storage for a personal static website through its gh-pages.

Jekyll, a Ruby based static website generator, is supported and is a great tool to give a dynamic taste to your static site.

First, let’s install Jekyll locally.

Jekyll

Install ruby:

There are several ways to install Ruby. Here are 2 of them:

• Install Ruby from your distribution package manager, following the official documentation: https://www.ruby-lang.org/en/documentation/installation/

• Or install RVM (Ruby Version Manager) so you can have several different versions of ruby on your system: https://rvm.io/

Install Jekyll and bundler

$ gem install jekyll bundler

Initialize your Jekyll website

$ mkdir mywebsite
$ cd mywebsite
$ bundle install
$ bundle exec jekyll s

Browse your local website

http://127.0.0.1:4000

Create a new post/page/article

Jekyll generates your pages written in markdown syntax under mywebsite/_posts.

Let’s create a new post:

cd mywebsite/_posts

vi $(date +"%F")-my-first-article.md

	---
	layout: post
	title:  "My first post"
	date:	"YYYY-MM-DD"		### REPLACE YYY-MM-DD BY THE CURRENT DATE
	categories: 

	---
	## Congratulations
	
	You have written your first article!

Or, the fast way with copy/paste:

cd mywebsite/_posts && cat <<EOF > $(date +"%F")-my-first-article.md
---
layout: post
title:  "My first post"
date:	"$(date +"%F")"
categories: 

---
# Congratulations!

You have written your first article!
EOF

Git

Install git

For RHEL/CentOS/Fedora:

# yum install git
or
# dnf install git

For Debian based distributions:

# apt install git

Github configuration

Create a GitHub account.

Create a new repository (eg. mywebsite).

Create a Readme file in your main branch (master branch).

Create an additional branch gh-pages and activate gh-pages on your repository.

Clone your repository locally:

$ git clone https://github.com/<github_username>/mywebsite.github.io.git

Copy all the files from mywebsite/_site to mywebsite.github.io

$ cp -R mywebsite/_site/* mywebsite.github.io.git/

Enter your cloned repo:

$ cd mywebsite.github.io

Update your remote repository with the new files:

$ git checkout master
$ git add .
$ git commit -m "first commit"
$ git push origin master
$ git checkout gh-pages
$ git rebase master
$ git push origin gh-pages
$ git checkout master

To ease the procedure, you can set an alias in mywebsite/_site/.git/config

[alias]
    sync-ghpages = !git checkout gh-pages && git rebase master && git push origin gh-pages && git checkout master

Now, you only have to commit and push to the master branch, then use the alias sync-ghpages to synchronize the gh-pages with the master branch.