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)"
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.
For the second one just press simple close.
Then after you'll be notified with this message.
Downloading Command Line Tools for Xcode
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
Wait for Homebrew installation will finish.
==> Downloading and installing Homebrew...
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
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
In system preferences, you can find out this message in case you have a fresh un-updated version of macOS Catalina.
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.
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"
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
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
And check if code is there. You should fine inside this info.
export PATH="/usr/local/opt/ruby/bin:$PATH"
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) ?
Press Y
and then ENTER
. And then after this short command to reload ~/.zshrc
file.
source ~/.zshrc
Check where all ruby installation is located after all.
which ruby
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
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
You will see this command.
ruby 2.7.2p137
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
And install the latest version with this command.
gem update --system
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
Double-check our versions for Gems and Bundler let's check.
gem -v
bundler -v
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
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
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
Gem Jekyll Bundler Installation
Now let's add Jekyll's necessary Gems for your Jekyll website with bundle
.
bundle add jekyll
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 .
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]
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
Let's Serve Website
Now just simply serve the website into localhost with this command.
bundle exec jekyll serve
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.
Top comments (1)
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.