In the past, I’ve delved in the blogging universe using Blogger, Tumblr, and even WordPress, but after a while, I fell disenchanted with what they offered.

I learned about GitHub Pages back in 2013 via the one and only Phil Haack (Dr. Jekyll and Mr. Haack), and now it is that I take the plunge and start experimenting myself.

So here is a guide on how I got myself started using GitHub pages.

Table of Contents

  1. Assumptions
  2. Getting started with GitHub pages
  3. Getting rbenv set up on macOS
  4. Installing a ruby version and setting a global version with rbenv
  5. Getting Jekyll on macOS
  6. Finding a Jekyll theme
  7. Editing and testing your Jekyll blog on your local machine
  8. Publishing your site and all future posts
  9. Extras

Assumptions

You are already familiar with GitHub and Git and know your way around the command line.

Let’s get started!

Getting started with GitHub pages

There’s a very comprehensive guide on how to get started with GitHub pages here or over here, but if you would like to create your posts locally, after you’ve created your repo, clone it on your computer, and continue with this guide.

Getting rbenv set up on macOS

You might know that macOS comes with ruby and python, but considering using them for your personal projects and messing with them is not recommended.

So this is where rbenv comes in and saves the day. And the Jekyll on macOS is a great step-by-step guide on how to set up Xcode, Homebrew, and rbenv on your macOS machine.

Just follow these steps:

  1. Install Command Line Tools for Xcode (link)
  2. Install Homebrew
     $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
    
  3. Install rbenv
     $ brew install rbenv
    
    
  4. Set up rbenv integration with your shell
     $ rbenv init
    
    
  5. Add it to your bash profile
     $ echo 'eval "$(rbenv init -)"' >> ~/.zshrc
    
  6. Restart your shell so the path changes take effect
     $ exec "$SHELL"
    
  7. Check your rbenv installation
     $ curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash
    

Installing a ruby version and setting a global version with rbenv

  1. List stable versions
     $ rbenv install --list
     2.5.8
     2.6.6
     2.7.2
     jruby-9.2.13.0
     maglev-1.0.0
     mruby-2.1.2
     rbx-5.0
     truffleruby-20.2.0
     truffleruby+graalvm-20.2.0
        
     Only latest stable releases for each Ruby implementation are shown.
     Use 'rbenv install --list-all' to show all local versions.
    
  2. Install your desired version.
     $ rbenv install 2.7.2
    
  3. Once installed, list all versions
     $ rbenv versions
    
  4. Select your desired version
     $ rbenv global 2.7.2
     $ rbenv rehash
    

And you’re all set!

Getting Jekyll on macOS

After installing Xcode and Ruby, let’s go straight to installing Jekyll.

As of this writing, the latest version for Jekyll is 4.1.1, which is not yet supported by GitHub Pages (check here for up-to-date dependencies), that’s why we specify version 3.9.0.

To Install Jekyll we need to run the following commands:

$ gem install bundler
$ gem install jekyll -v 3.9.0

To verify, run the following commands:

$ which jekyll 
/Users/thecesrom/.rbenv/shims/jekyll
$ bundle exec jekyll --version
jekyll 3.9.0

Now that we’re ready, let’s find a theme!

Finding a Jekyll theme

While you may use the options provided by GitHub, I found Beautiful Jekyll over at JAMstack themes.

The instructions are straightforward; found here.

Once you get it set up, open a Terminal session in your blog’s root directory and run the following command:

$ bundle install

This will install all necessary dependencies and get you one step closer.

Editing and testing your Jekyll blog on your local machine

I am using Visual Studio Code for editing my site, but you may use another text editor or IDE out there.

And after some customization I just run:

$ bundle exec jekyll serve

vscode

And my site is now live at http://127.0.0.1:4000/

And this is the final product:

screenshot

Publishing your site and all future posts

With the power of commit and push you can accomplish anything.

Extras

Here are a few links and extensions that you might find useful:

Thanks for reading!