GitHub Pages, Jekyll and Centos 7

I have been digging into GitHub Pages as an alternative blog platform in case Blogger follows Google+ to the Great Big BitBucket in the Sky. WordPress is an obvious alternative to Blogger but GitHub Pages offers a simpler escape route.

This post describes how to create and maintain a personal web site on GitHub Pages, and to migrate Blogger content to the new site.

GitHub Pages

GitHub Pages is a static website hosting service for personal, organizational, or project-specific pages that are driven directly from your GitHub repository.

You can use either HTML or Markdown to create the pages. It is a static site hosting service so it doesn't support server-side code such as PHP, Ruby, or Python.

GitHub Pages can work with any static site generator, but for ease of use it is tightly integrated with the Jekyll static site generator.

You feed it Markdown text and it cranks out a static website, using kramdown to parse the Markdown syntax to generate the HTML pages.

github.io

A website generated by GitHub Pages is hosted at <username>.github.io where <username> is the name of your GitHub account.

GitHub Pages generates the web site from content stored in a repository that you create using the same name.

Follow the instructions here to create your new repository <username>.github.io.

Clone the repository to your development environment so that you can work on it using your favourite editor, then push the changes back up to GitHub. After a moment or two, you will see the fruits of your labours by browsing to https://<username>.github.io.

You could continue to work on this simple local copy to build up a functionally rich website, but you will have to set up a Jekyll development environment to do things like migrate posts from Blogger.

The next section describes how to install Jekyll and use it to generate the website.

Jekyll development environment

Install RVM and Ruby

Jekyll is a Ruby Gem that must be installed on your system, which in my case is a Centos 7 workstation. These instructions should work for other RPM-based distros like RHEL or Fedora.

The pre-requisites are Ruby version 2.4.0 or above, as well as GCC and Make.

Install the development tools group which includes GCC and Make:

$ sudo yum update -y
$ sudo yum install @development-tools

The version of Ruby in the Centos 7 repo does not meet the requirements (it is version 2.0), so build the Ruby Version Manager RVM and use it to install the latest version.

Get the GPG keys and install RVM:

$ sudo gpg2 --keyserver hkp://pool.sks-keyservers.net --recv-keys \
    409B6B1796C275462A1703113804BB82D39DC0E3 \
    7D2BAF1CF37B13E2069D6956105BD0E739499BDB
$ sudo \curl -sSL https://get.rvm.io | bash -s stable

Note that for reasons best known to the RVM developers, they have prefixed the curl command with a backslash to suppress any aliases for curl. It is not a typo.

Add your Linux user to the RVM group so that it can be used as a non-root user:

$ sudo usermod -a -G rvm <devuser>
$ sudo getent group rvm
rvm:x:1001:<devuser>

where <devuser> is your Linux username.

Logout and login again to activate the group membership.

List all known rubies to find the latest version of Ruby:

$ rvm list known | less

Install the latest version (2.6 in this case) and check the version numbers:

$ rvm install ruby-2.6
$ rvm use 2.6 --default

$ ruby -v
ruby 2.6.0p0 (2018-12-25 revision 66547) [x86_64-linux]

$ gem -v
3.0.1

Install Jekyll and the gem bundler:

$ gem install jekyll bundler

Generate a Jekyll website

Now we will use Jekyll to generate the website from scratch, replacing the simple version you created above, as follows:

$ rm -rf <username>.github.io
$ jekyll new <username>.github.io

Fire it up:

$ cd <username>.github.io
$ bundle exec jekyll serve

Browse to http://localhost:4000 to see your new site. 

Edit _config.yml to change the blog title and other site-specific details. The inaugural post is in _posts/yyyy-mm-dd-welcome-to-jekyll.markdown. Edit it as you see fit.

Note that the default site that Jekyll generated is powered by two gems:

gem "jekyll", "~> 3.8.5"
gem "minima", "~> 2.0"

Before you publish the website to github.io, replace these two with the github-pages gem that has been commented out in the Gemfile, to get the full value of GitHub Pages. Edit your Gemfile to delete these two default Jekyll gems and replace them with the gem that contains the GitHub Pages functionality by uncommenting the line gem "github-pages", group: :jekyll_plugins then update the site to install the gems:

$ vi Gemfile
$ bundle update

Stop and restart the site to make sure all is well.

Publish to github.io

To publish this on github.io, you need to push the newly generated contents to the repo that you created above.

Initialize the current working directory as a Git repository:

$ git init

Stage and commit the files:

$ git add --all
$ git commit -m "Initial commit"

Link your newly generated website to the repo <username>.github.io that you created above by adding the URL of the project repo to the origin of the local git repo and push the contents to GitHub:

$ git remote add origin git@github.com:<username>/<username>.github.io.git
$ git push -u origin master --force

The --force option will overwrite the contents of the GitHub repo with the contents of the newly generated website, so be careful.

Migrate Blogger posts

Migrating your Blogger posts is straightforward because Jekyll provides importers to move from other blog platforms.

Follow these instructions to create a backup file of your Blogger posts called blog-MM-DD-YYYY.xml.

Import the posts into Jekyll:

$ ruby -r rubygems -e 'require "jekyll-import";
    JekyllImport::Importers::Blogger.run({
      "source"                => "/path/to/blog-MM-DD-YYYY.xml",
      "no-blogger-info"       => false, 
      "replace-internal-link" => false, 
    })'

This will generate the posts in _posts. Note that “Labels” will be included in the export as “Tags”.

If you uploaded images to your Blogger posts, they will be visible as links to your original blog, so you will have to download them and insert them locally before you decommission the old blog.