Setting up Jekyll for Github Pages

So, I have been using WordPress as my personal blogging tool. I don’t need any fancy stuff or lots of customizations for my site as all I would like to do is to document what I’ve learned and share with others. In this aspect, an out-of-the-box WordPress site with a few plugins works great for me. However, when I heard about GitHub Pages, I couldn’t wait to try it. Why? Because it is free. Take a look at this bill from my hosting company this year:

To most people, $143 is not a lot of money. However, I can’t justify spending over $100 on a very basic site every year when there is a free alternative. Moreover, this fee goes up every year! Look at how much it was last year:

While I will pay to keep my domain, it doesn’t make sense for me to continue with the hosting service. I am motivated/determined to get my WordPress site migrated to GitHub before the hosting service expires!

I’ve also decided to document my journey of setting up Jekyll and using it as a blogging tool on my GitHub site. So here you go!

Prerequisites – Ruby and Jekyll

Per the Jekyll official website, Jekyll requires Ruby version 2.2.5 or above.

I had to update my Ruby as the version shipped with my Mac OS definitely did not meet this requirement.

[515] cindylai@MacBook-Pro-201 - 03:28:10 $ ruby -v
ruby 2.2.2p95 (2015-04-13 revision 50295) [x86_64-darwin14]

So, I tried:

rvm install ruby-2.5.1

And got this message:

Warning! PATH is not properly set up, /Users/cindylai/.rvm/gems/ruby-2.2.2/bin is not at first place.
         Usually this is caused by shell initialization files. Search for PATH=... entries.
         You can also re-add RVM to your profile by running: rvm get stable --auto-dotfiles
         To fix it temporarily in this shell session run: rvm use ruby-2.2.2
         To ignore this error add rvm_silence_path_mismatch_check_flag=1 to your ~/.rvmrc file.
Already installed ruby-2.5.1.
To reinstall use:

    rvm reinstall ruby-2.5.1

Well, at least there are instructions on how to fix it. To reload RVM, simply do:

rvm get stable --auto-dotfiles

And now, the following confirms that I’m on the latest version:

[525] cindylai@MacBook-Pro-201 - 03:33:46 $ ruby -v
ruby 2.5.1p57 (2018-03-29 revision 63029) [x86_64-darwin17]

I then proceeded to install Jekyll and bundler gems:

gem install jekyll bundler

Creating a new Jekyll site

At this point, I thought I was done with all the set up and ready to create my Jekyll site, so I did:

jekyll new myblog

And of course, it didn’t go as planned. This is what it returned:

/Users/cindylai/.rvm/gems/ruby-2.5.1/gems/bundler-1.16.4/lib/bundler/resolver.rb:285:in `block in verify_gemfile_dependencies_are_found!': Could not find gem 'github-pages' in any of the gem sources listed in your Gemfile. (Bundler::GemNotFound)

This time Ruby didn’t tell me how to fix it, but I found a helpful answer , which is to run:

bundle install

After that, Ruby successfully installed Jekyll and other dependencies from the GitHub Pages gem.

Now, I ran

jekyll new myblog

again and this time it worked.

Next, I ran:

bundle exec jekyll serve

Jekyll successfully served up my blog but there are a couple of warnings:


Configuration file: none
            Source: /Users/cindylai/Documents/Personal/github/cindyyklai.github.io
       Destination: /Users/cindylai/Documents/Personal/github/cindyyklai.github.io/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
     Build Warning: Layout 'post' requested in myblog/_posts/2018-09-12-welcome-to-jekyll.markdown does not exist.
   GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.
     Build Warning: Layout 'page' requested in myblog/about.md does not exist.
     Build Warning: Layout 'home' requested in myblog/index.md does not exist.
                    done in 2.405 seconds.
 Auto-regeneration: enabled for '/Users/cindylai/Documents/Personal/github/cindyyklai.github.io'
    Server address: http://127.0.0.1:4000
  Server running... press ctrl-c to stop.

Upon googling this issue, I stumbled across https://github.com/jekyll/jekyll/issues/6047. And based on one of the comments, this seems to be expected starting Jekyll 3.2. This is the statement on the Jekyll official site:

And I confirm that I’m on 3.7.4:

[536] cindylai@MacBook-Pro-201 - 08:54:44 $ jekyll -v
jekyll 3.7.4

Leave a Reply