Preface

This tutorial covers how to use Jekyll and GitHub Pages to host a free blog like this one. Bash commands are applicable to macOS Sierra version 10.12.4.

Installs

Git

By default git is not installed in macOS Sierra. The Xcode command line tools can be installed or you can install Git directly from a git mirror. The advantage of installing it from the mirror is Xcode lags behind the most up to date git version. Download and install the newest git version from the link below.

https://sourceforge.net/projects/git-osx-installer/files/

Newer versions of macOS have a security protocol that causes some issues installing programs from unidentified developers and location of the install. Run the PKG file downloaded from Sourceforge and macOS will not install.

The workaround is to open computer Settings, go to Security & Privacy, and Click the lock to make changes. Once OK is clicked on the below menu the Security & Privacy window updates with an Open Anyway option. Now proceed through the git install with the default location.

At the Terminal now type which git. If it returns /usr/bin/git it need to be changed to /usr/local/bin/git instead. To do this the $PATH variable needs to have the latter path before the first. Either edit or add this line to your ~/.bash_profile file in your home directory using the terminal commands below.

nano ~/.bash_profile

Add this line which concatenates the local path to the very beginning of /etc/paths.

export PATH=/usr/local/bin:$PATH

Now exit nano using ^X and make sure it is saved by pressing Y. Restart Terminal and type which git now should return the git path being in the local directory.

/usr/local/bin/git

Xcode Command Line Tools

The Xcode command line tools also must be installed to install other things like Jekyll. Open the terminal and type the following. A new series of dialogs will pop up, just follow the prompts to install.

xcode-select --install

Jekyll

Jekyll can be installed using Rubygems but macOS Sierra has new security features not allowing installs in default gem install location. This can be worked around by providing an install path as the last option when installing. Bundle needs to be installed first then Jekyll.

gem install bundle /usr/local/bin  
gem install jekyll /usr/local/bin

GitHub Setup

Go to GitHub and create a new repository and do not initialize a README file. On the next page copy the link to your repository and clone it locally. This will create an empty directory in the Documents called tutorial.

cd ~/Documents
git clone https://github.com/aricbeaver/tutorial.git

Now go to the settings of your repository and change the GitHub Pages to use the master branch. Alternatively, you can create a new branch called gh-pages and GitHub will automatically assume it is a Pages branch.

Create Jekyll Blog

Creating a Jekyll Blog is very easy.

cd ~/Documents
jekyll new tutorial
cd tutorial
jekyll serve

By default Jekyll will serve port 4000 on localhost so it can be access easily by typing the following into your browser’s address bar.

http://localhost:4000

I didn’t want to use the default Jekyll theme instead Jekyll Clean Dark theme. There are hundreds of other themes at http://jekyllthemes.org/.

Now the initial Jekyll project will be deleted and a new one pulled from the Jekyll Clean Dark theme repository to be forked into my own custom blog.

cd ~/Documents
rm -rf tutorial/
git clone https://github.com/aricbeaver/tutorial.git
cd tutorial
git pull https://github.com/streetturtle/jekyll-clean-dark.git
git push -u origin master

The _config.yml needs to be edited to get the theme fully functional. The url and baseurl need to be updated.

url: https://<insert_your_github_username>.github.io
baseurl: ''

Now add, commit, and push the files to GitHub.

cd ~/Documents/tutorial
git add .
git status # Not required but shows commit queue
git commit -m 'modified configuration to work with GitHub Pages'
git push

Accessing the blog at https://insert_your_github_username.github.io/tutorial/ should show the dark theme’s example blog.

Add Posts

To add posts just create a new file in the _posts directory that uses the header format defined in the other example posts. Here is an example of this blog post. Be careful to not use a date that is in the future or it will not render that page when using Jekyll serve.

2017-04-30-jekyll-githubpages-setup.md

---
layout: post
title: "Jekyll and Github Pages Blog Setup"
date: 2017-04-30 01:50:00
description: Tutorial on how this blog was setup.
tags: 
 - blog
 - code
---

# Preface
This tutorial covers how to use Jekyll and GitHub Pages to host a free blog like this one. Bash commands are applicable to macOS Sierra version 10.12.4.

# Installs
## Git
By default git is not installed in macOS Sierra. The Xcode command line tools can be installed or you can install Git directly from a git mirror. The advantage of installing it from the mirror is Xcode lags behind the most up to date git version. Download and install the newest git version from the link below.

Other Things

• A custom domain name can be created by purchasing your domain and setting this up in GitHub Pages settings. There are instructions on GitHub on this process.
• If a custom domain name is used HTTPS is not possible through GitHub Pages settings but Cloudflare can be used to set this up. There are instructions on a few other blogs about this.