Desired Persona

Install Jekyll on macOS

· 5 min read

I was looking for a tool that can build websites that are fast, simple and secure. These websites needed to be static because I didn’t want to deal with databases or a traditonal content management system (CMS) like WordPress or Ghost. After a lot of thought I decided to use Jekyll.

So what is Jekyll?

Jekyll is a tool for transforming your plain text into static websites and blogs. It is simple, static, and blog-aware. Jekyll uses the Liquid templating language and has built-in Markdown and Textile support. It also ties in nicely to Github Pages so you have the option to host your website for free. I highly recommend you join Jekyll Talk the official support forum, where users and contributors can ask questions and discuss all aspects of Jekyll.

Preparing to install Jekyll

Installing Jekyll is easy and straight-forward, but there are a few requirements you’ll need to make sure your system has before you start.

Install homebrew from the website.

/usr/bin/ruby -e "$(curl -fsSL

Install the latest version of Ruby using homebrew

brew install ruby

Check the Ruby version installed

ruby -v

Install bundler

gem install bundler

Go to the Mac app store and Install Xcode if you haven’t already. Then install the Xcode Command Line Tools.

xcode-select --install

Installing Jekyll

Install Jekyll

gem install jekyll

Check Jekyll version

jekyll -v

Change directory to the location where you want to create your site. I have chosen to keep all my Jekyll sites in a directory called Jekyll located in /Sites/Jekyll/.

cd ~/Sites/Jekyll/

Create a new Jekyll site. Replace site-name below with your own site name.

jekyll new site-name

Change directory to the new site you just created

cd ~/Sites/Jekyll/site-name/

Preview your new site with the command

bundle exec jekyll serve

Jekyll will now watch for changes, and regenerate automatically. Your static website is generated in the _site directory.

To view your Jekyll website open http://localhost:4000 in a browser.

How to update Jekyll

Bundler will update all your gems to the latest versions by simply running bundle update in a Terminal window.

How to create and update a GitHub repository

Before i continue with this tutorial, its worth mentioning that you can learn to use Git in 15 minutes.

Install Git

brew install git

Open Terminal and go to your website directory

cd ~/Sites/Jekyll/site-name/

Your first instinct, when you start to do something new, should be to type git init. Once inside your Jekyll site directory initialize it as a Git repository with the command

git init

Good job! As Git just told us, our websites directory now has an empty repository in /.git/. The repository is a hidden directory where Git operates.

Next up, let’s type the git status command to see what the current state of our project is

git status

Create a readme file

echo "# This is my first jekyll website" >>

Create a .gitignore file right away, to indicate all of the files you don’t want to track.

touch .gitignore

Open the hidden .gitignore file with the following command

nano .gitignore

Add the following to the .gitignore file


In order to begin tracking these new files, you use the command git add. If you modify a file after you run git add, you have to run git add again to stage the latest version of the file

git add
git add .gitignore

Use git status to determine which files are in which state (e.g untracked files)

git status

After updating your website files in your website directory you can actually use git add . to add all untracked files at once.

git add .

Now you can commit your changes to your GitHub repository.

git commit

Alternatively, you can type your commit message inline with the commit command.

git commit -m "YOUR MESSAGE HERE"

Now you’ve created your first commit!

TIP: Adding the -a option to the git commit command makes Git automatically stage every modified file that is already tracked before doing the commit, allowing you to skip the ‘git add’ part.

git commit -a -m "YOUR MESSAGE HERE"

Next created a new empty GitHub repository. Login to and click the ‘+’ icon and select ‘New repository’. Enter a repository name and then click ‘Create repository’.

In Terminal run the following command but first replace ‘username’ with your own GitHub username and ‘repository’ with the repository name you just created.

git remote add origin

Now you are ready to push your changes to your new GitHub repository.

git push -u origin master

After your first push, you can simply type git push to push future change to your GitHub repository.

git push

Publish Jekyll to GitHub Pages

Create a new branch called gh-pages.

git branch gh-pages

Switch to gh-pages branch.

git checkout gh-pages

TIP: You could also do git checkout -b gh-pages to create and switch branch in one command.

Next you can delete the master branch on your local machine if you dont need to switch between two branches for development. We only need to use the gh-pages branch in future for hosting and keeping track of our static website changes.

git branch -D master

Push changes to gh-pages repository

git push origin gh-pages

Go to your Jekyll repository page on GitHub. Click on ‘Settings’. In the ‘Branches’ section, change the ‘Default branch’ in the dropdown menu to the newly created ‘gh-pages’ branch.

Now you can delete the master branch from GitHub

git push origin :master

Your Jekyll website is now live on GitHub pages.

Setting up a custom domain on GitHub Pages

Create a CNAME file

touch CNAME

Open the CNAME file using the following command.

nano CNAME

Add your websites domain name in the following format and save your changes.

I then updated my domain registrar’s DNS to point to Cloudflare.

Setting up Cloudflare is really simple. You just need to create two A name records that point your domain name to GitHub’s IP Addresses and

Then setup a WWW subdomain redirect by creating a CNAME record in Cloudfare that points to your domain name.

It will take awhile for your changes to take effect but your domain should now point to your Jekyll website that is hosted on GitHub pages.

How to update your Jekyll website

Jekyll comes with a built-in development server that will watch for changes and regenerated automatically by using

bundle exec jekyll serve

When you are finished making changes, it’s time to build the latest version of your jekyll website for production.

JEKYLL_ENV=production bundle exec jekyll build

TIP: As you can see above im using the JEKYLL_ENV=production prefix before the bundle exec jekyll build command to only include Google Analytics when Jekyll is set to production environment.

Check file status

git status

Add all untracked files

git add .

Commit changes

git commit -a -m "YOUR MESSAGE HERE"

Push changes to your GitHub repository

git push

Well done! Your Jekyll website is now up to date.

Did you find this tutorial helpful?