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 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.
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.
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
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"
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.
And check if code is there. You should fine inside this info.
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) ?
Y and then
ENTER. And then after this short command to reload
Check where all ruby installation is located after all.
You will see the full path in the terminal prompt same as in the previous command you have entered.
To be definitely sure you can check onceagain your
.zshrc file with
You'll find there
export PATH="/usr/local/opt/ruby/bin:$PATH" info in it has been added.
And double-check the Ruby version.
You will see this command.
Well, Ruby is finally set up, now we are ready to go with the Jekyll installment.
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'
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.
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.
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
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
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.
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
Now let's add Jekyll's necessary Gems for your Jekyll website with
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
This directory is hidden but can be accessed via a shortcut that will reveal it. Use
SHIFT + CMD + .
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
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]
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.
Now just simply serve the website into localhost with this command.
bundle exec jekyll serve
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.