GitHub Pages, Jekyll and Centos 7

I looked into WordPress as an alternative to Blogger but GitHub Pages offers a simpler escape route, so this post describes how to create and maintain a personal website 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

Start by logging into your GitHub account and creating a new repository called <username>.github.io, where <username> is the name of your GitHub account (see the instructions here).

GitHub Pages will then generate a website from the content stored in that repository. It is hosted at <username>.github.io, where <username> is the name of your GitHub account, so browse to https://<username>.github.io to see the fruits of your labours.

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 changes on github.io.

You could continue to work on this simple local copy to build up a functionally rich website, but you should 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. The instructions that follow 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.

The first step is to install the development tools group which includes GCC and Make:

1sudo yum update -y
2sudo yum install @development-tools

The version of Ruby in the Centos 7 repo does not meet the requirements (it must be at least 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:

1sudo gpg2 --keyserver hkp://pool.sks-keyservers.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
2sudo \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:

1sudo usermod -a -G rvm <devuser>
2sudo getent group rvm
3   # 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:

1rvm list known | less

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

1rvm install ruby-2.6
2rvm use 2.6 --default
3
4ruby -v
5   # ruby 2.6.0p0 (2018-12-25 revision 66547) [x86_64-linux]
6
7gem -v
8   # 3.0.1

Install Jekyll and the gem bundler:

1gem 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:

1rm -rf <username>.github.io
2jekyll new <username>.github.io

Fire it up:

1cd <username>.github.io
2bundle exec jekyll serve

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

Configure the website

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:

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

Before you publish the website to github.io, edit your Gemfile to comment them out, and uncomment the line gem "github-pages", group: :jekyll_plugins then update the site to install the github-pages gem to get the full value of GitHub Pages:

1vi Gemfile
2bundle 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, so initialize the directory with your new site as a Git repository, then stage and commit the files:

1git init
2git add --all
3git commit -m "Initial commit"

Link your newly generated website to the repo .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:

1git remote add origin git@github.com:<username>/<username>.github.io.git
2git push -u origin main --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, then import the posts into Jekyll:

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

This will generate the posts in _posts.

Note that:

• “Labels” will be included in the export as “Tags”.
• Images in your Blogger posts will be visible as links to your original blog, so you will have to download them manually and insert them locally before you decommission the old blog.