loading...
Cover image for Install Jekyll On MacOs Terminal

Install Jekyll On MacOs Terminal

stankukucka profile image Stan k2ck4 ・8 min read

Why Choose Jekyll Over WordPress

For some projects is good to go with WordPress for a practical reason. Sometimes it's the company's best practice and sometimes it's used from the early beginning of a project you have already become part of.

For smaller, static websites I found out Jekyll was a good choice. In case you would like to build online documentation for your upcoming project, API, or even small personal website or portfolio without hassle around with database, then definitely have a look on Jekyll. No need for a backup database or tiresome plugin updates or system lengthy upgrades - simple just your static content.

Main benefits after deployment of such a website? It's just simple plain static HTML, CSS, and few JS files to load from your hosting or cloud deployment so you'll be rewarded with a nice speed load if your front-end is smartly written.

I Have Been Struggling With It

I have been struggling in the past while trying to install this solution on macOS and I have run over many articles "How to do it". There's a lot of different methods I have found out there, but after going through my own struggles with it, I wanted to share the most concise solution I came up with.

This tutorial is my answer to all the headaches I have had. It's a compact and detailed answer to this installation process in this case without a Docker image just whole installation to your macOS system via command prompt.

Xcode And Homebrew Installation

Ruby is part of the standard installation of macOS Catalina. It's not last ruby update, just ruby 2.6.3p62, but it's there.

Let's imagine you have a fresh installation of macOS Catalina. The first thing first starts with the Homebrew installation. Visit https://brew.sh/ and copy-paste this command into the terminal.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
Enter fullscreen mode Exit fullscreen mode

You'll be asked for pressing RETURN button. Then these small messages will popup's on your right top corner.

For the first one press Install.

Alt Text

For the second one just press simple close.
Alt Text

Then after you'll be notified with this message.

Downloading Command Line Tools for Xcode
Enter fullscreen mode Exit fullscreen mode

Yeah, this is the longest part to wait for till installation will pass the whole process. After a few minutes, you'll see this output within the terminal and asked for a password.

Downloading Command Line Tools for Xcode
Downloaded Command Line Tools for Xcode
Installing Command Line Tools for Xcode
Done with Command Line Tools for Xcode
Done.
==> /usr/bin/sudo /bin/rm -f /tmp/.com.apple.dt.CommandLineTools.installondemand.in-progress
Enter fullscreen mode Exit fullscreen mode

Wait for Homebrew installation will finish.

==> Downloading and installing Homebrew...
Enter fullscreen mode Exit fullscreen mode

When it's done you'll see this in your command shell prompt.

==> Next steps:
- Run `brew help` to get started
- Further documentation: 
    https://docs.brew.sh
Enter fullscreen mode Exit fullscreen mode

In case you would like to update Ruby on the system and ruby -v gives you info about the lower version number of Ruby installation you could have, just type in this command brew reinstall ruby to update it as a whole. In the next chapter, we are going with Ruby install from scratch with help of brew install.

Ruby Update or Installation On Your macOS

The latest ruby version you can check on official website as well. There is no need to download it from here. We gonna make it via command. As brew is on your system already, it's a much more smooth process to install it freshly with this command brew install ruby so just simply execute it.

brew install ruby
Enter fullscreen mode Exit fullscreen mode

In system preferences, you can find out this message in case you have a fresh un-updated version of macOS Catalina.

Alt Text

Later on, you may be "rewarded" by this message in your right top corner. You can restart later on and let the system update itself to avoid potential issues of an incomplete update process.

Alt Text

At the same moment, you may find after ruby installation brief info about finalized ruby installation. It's formed into 5 lines output inside the terminal.

If you need to have ruby first in your PATH run:
  echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc

For compilers to find ruby you may need to set:
  export LDFLAGS="-L/usr/local/opt/ruby/lib"
  export CPPFLAGS="-I/usr/local/opt/ruby/include"
Enter fullscreen mode Exit fullscreen mode

Under message If you need to have ruby first in your PATH run:, we'll grab command to copy-paste to execute inside your terminal.

echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc
Enter fullscreen mode Exit fullscreen mode

With this, we will let the system know about the place where ruby should be located. Basically, we will write info into .zshrc (it's similar to .bashrc) with this command.

Written info into .zshrc file will be executed everytime when you'll log into the system. Before you can check .zshrc with this nano .zshrc what's there and you'll find it empty. So let's check if full Ruby path of your new updated version of Ruby is there.

So open that file we have already mentioned.

nano ~/.zshrc
Enter fullscreen mode Exit fullscreen mode

And check if code is there. You should fine inside this info.

export PATH="/usr/local/opt/ruby/bin:$PATH"
Enter fullscreen mode Exit fullscreen mode

If you did any changes press CTRL + X to close file. You'll be asked for saving the file.

Save modified buffer (ANSWERING "No" WILL DESTROY CHANGES) ? 
Enter fullscreen mode Exit fullscreen mode

Press Y and then ENTER. And then after this short command to reload ~/.zshrc file.

source ~/.zshrc
Enter fullscreen mode Exit fullscreen mode

Check where all ruby installation is located after all.

which ruby
Enter fullscreen mode Exit fullscreen mode

You will see the full path in the terminal prompt same as in the previous command you have entered.

/usr/local/opt/ruby/bin/ruby
Enter fullscreen mode Exit fullscreen mode

To be definitely sure you can check onceagain your .zshrc file with nano ~/.zshrc
You'll find there export PATH="/usr/local/opt/ruby/bin:$PATH" info in it has been added.

And double-check the Ruby version.

ruby -v
Enter fullscreen mode Exit fullscreen mode

You will see this command.

ruby 2.7.2p137
Enter fullscreen mode Exit fullscreen mode

Well, Ruby is finally set up, now we are ready to go with the Jekyll installment.

Jekyll Theory before Installation

Let's start with a brief and most important theory. Without knowing this part I have been struggling with installment most of the time. Understanding helped me to grasp the concept of how Jekyll works and what are the most crucial benefits of Gem based theme in other words what Ruby Gems are and how they work.

You can create your theme Gem from the theme you have developed to help others to download it, but this is not a part of this tutorial.

To fully understand what Jekyll Gem is about, is good to know that Gem is the information used to build your static website like Jekyll-feed, Jekyll-sitemap, Jekyll-pages, Jekyll-seo-tag, etc.

More you can find before installation simple just searching for Jekyll here.

Let's understand Gem based theme info as something located far away from us on Rubygems.org. It's very practical in case we want to have an updated version of the theme that is publicly accessible on this website in form of Gem. So Gem is information about the public Rubygem theme as well about Jekyll static website builder.

When we install Jekyll it will comes with very simple Jekyll Theme Minima in other words with theme gem minima. Full command info with version status is gem 'minima', '~> 2.5', '>= 2.5.1'

How To Manage Gems

The whole Jekyll generator is based on Ruby. How to manage Ruby Gems you'll see in upcoming words. To see a list of Gems there is nothing as much to do. It's easy peasy. It comes standard with Ruby installation you can check it with this command.

gem -v
Enter fullscreen mode Exit fullscreen mode

And install the latest version with this command.

gem update --system
Enter fullscreen mode Exit fullscreen mode

To see all list of Ruby gems on your system you can type gem list --local or gem server and visit then http://0.0.0.0:8808/. Shut down server with CONTROL + C.

In directory structure usr/local/lib/ruby/gems/2.7.0/gems you can find here list of Gems all created as directories.

Installation of Bundler

To be able to install Jekyll via Bundler let's install it with this simple command as another gem gem install bundler

gem install bundler
Enter fullscreen mode Exit fullscreen mode

Double-check our versions for Gems and Bundler let's check.

gem -v
bundler -v
Enter fullscreen mode Exit fullscreen mode

Create a Working Directory For Website

Let's make a working directory for your website for example on your desktop and enter into this directory.

cd Desktop
mkdir myjekyllwebsite
cd myjekyllwebsite
Enter fullscreen mode Exit fullscreen mode

Let's Inicial Bundle

Initial Bundle with bundle init. It will create Gemfile inside the working myjekyllwebsite directory. Open it with your editor to see what will happen next in meaning of commands written into it.

bundle init
Enter fullscreen mode Exit fullscreen mode

It will create Gemfile inside the directory you have already created and inform you about this inside the command line as well as shown hereunder.

Writing new Gemfile to /Users/os/Desktop/myjekyllwebsite/Gemfile
Enter fullscreen mode Exit fullscreen mode

Gem Jekyll Bundler Installation

Now let's add Jekyll's necessary Gems for your Jekyll website with bundle.

bundle add jekyll
Enter fullscreen mode Exit fullscreen mode

This command will write into Gemfile this line of code info gem "jekyll", "~> 4.1.1".

You can check it will add new directories inside the Gems directory structure as well here usr/local/lib/ruby/gems/2.7.0/gems/.

This directory is hidden but can be accessed via a shortcut that will reveal it. Use SHIFT + CMD + .

How To Execute Bundle

To make bundle work for you just type in this command.

bundle exec jekyll new --force --skip-bundle .
Enter fullscreen mode Exit fullscreen mode

It will add some additional info into Gemfile (info about minima theme as well) and website files into your working directory myjekyllwebsite.

gem "minima", "~> 2.5"
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
# gem "github-pages", group: :jekyll_plugins
# If you have any plugins, put them here!
group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
end

# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
# and associated library.
platforms :mingw, :x64_mingw, :mswin, :jruby do
  gem "tzinfo", "~> 1.2"
  gem "tzinfo-data"
end

# Performance-booster for watching directories on Windows
gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
Enter fullscreen mode Exit fullscreen mode

Now Install Theme Gem

This command will install theme gem minima into usr/local/lib/ruby/gems/2.7.0/gems/ with additional needed gems to build whole website correct way.

bundle install
Enter fullscreen mode Exit fullscreen mode

Let's Serve Website

Now just simply serve the website into localhost with this command.

bundle exec jekyll serve
Enter fullscreen mode Exit fullscreen mode

This will run the local server and the website can be now found on URL http://127.0.0.1:4000/ or http://localhost:4000 (it's the same).

Be sure you are inside the website working directory so cd myjekyllwebsite because the command will not work and probably will inform you with the message like Could not locate Gemfile or .bundle/ directory

To close local server just press CTRL + C to shut it down.

If you have questions or enjoyed this article, please feel free to comment or message me here or share if you think others might be interested too.

Thanks to Jason DeBloois for the cover image from Unsplash.

Discussion

pic
Editor guide
Collapse
eruizdechavez profile image
Erick Ruiz de Chavez

Very nice and detailed post, thanks for sharing 👏🏻!

I understand it might not fit your workflow, but you could save a lot of time and effort by using Jekyll’s docker images. I moved from following a pretty fragile setup with lots of dependencies on my computer to a clean and easy setup by just learning (and understanding) a couple of docker concepts (images, containers, volumes, ports). I really recommend it 👍🏻

github.com/envygeeks/jekyll-docker...

Collapse
stankukucka profile image
Stan k2ck4 Author

Hi Erick, you nailed it. I do definitely agree with you when it comes to the installation process with docker images. That's why I wrote an article right the day after dev.to/stankukucka/install-jekyll-.... Thanks once again for the suggestion.