Learning to Create Static Sites with Jekyll

Note: This post is work-in-progress learning-note and still in active development and updated regularly.

This week I took some break from my JS learning and spend some time reviewing static site generator application like Jekyll. I have been impressed with simple JS-based static site generator application like Jekyll or more complex application like React JS. Although such applications are little tech-savvy but their light weight feature have attracted many CMS users to simple static sites. I still enjoy using WordPress CMS for my sites but I am inspired by static sites as a learning challenge and practice my JS learning.

The goals of this learning project is to build a fully functional site like this one but will covered in multiple posts. In this post following goals are covered:

  • Learn about Jekyll – a static site generator
  • Basic  setup for Jekyll installation
  • Understand how Jekyll works
Why Static Sites?

Matt Billman’s article Why Static Site Generators Are The Next Big Thing in Smashing Magazine highlights the popularity of static sites in recent years. Static sites are known to be faster because they use simple HTML and plain CSS where as dynamic sites are run on server side language like PHP and often slower. Some key features of static sites include: faster speed, better security, simple markup without a database, and flexibility to authors. Some drawbacks of static sites include: lack of a simple admin dashboard, difficult to updating for non-techy users, and no real time content updates.

Basic Setup & Installation on MacOS

Jekyll is based on Ruby Gem can be run in machines with Ruby, Ruby Gems and X-code command line installed. In this post, installation on MacOS is only covered.

1. Set up Ruby included with the OS

MacOS High Sierra machine comes with Ruby 2.3.3 installed. Check the ruby version of MacOS machines using terminal:

#Check ruby version
ruby -v
ruby 2.3.3p222 (2016-11-21 revision 56859) [universal.x86_64-darwin17]

#Check Ruby Gem installation 
gem -v
2. Install Command Line Tool

It is essential to have command line tools to to be able to compile native extensions. From terminal command window check if Xcode Command Line has been installed in the machine by issuing following code. If not issue install Xcode as also shown below:

#Check if Xcode is installed
gcc -v
clang: error: no input files

#Install Xcode 
xcode-select --install
Apple LLVM version 9.1.0 (clang-902.0.39.1)
Target: x86_64-apple-darwin17.5.0
Thread model: posix
InstalledDir: /Library/Developer/CommandLineTools/usr/bin

An output similar above display confirms that XCode CommandLine Tools have been installed in the machine.

3. Install Jekyll Bundler

Jeckyll bundler is essential to handle plugins & themes. Bundler is a package manager that will aid you in installing all the Jekyll dependencies. To quote from Jekyll documentation: “Bundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed.” It’s similar to how NPM manages JavaScript dependencies.

 sudo gem install bundler
 # expected output
Successfully installed bundler-1.16.1
Parsing documentation for bundler-1.16.1
1 gem installed

A successful install displays 1 gem installed message. The sudo gem install bundler command installs the bundler gem through RubyGems. Once it is installed — it is not needed every time a  new Jekyll project is created. Some other details about bundler from jekyll documentation:

bundler is a gem that manages other Ruby gems. It makes sure that the gems and gem versions are compatible, and that you have all necessary dependencies required in development, staging, and production.

The Gemfile and Gemfile.lock files inform Bundler about the gem requirements in your site. If your site doesn’t have these Gemfiles, you can omit bundle exec and just run jekyll serve.

4. Create Gemfile & Install Budle

Create a new directory my-jeckyll-site on desktop and add a file named Gemfile (without file extension). Now add the following codes into the Gemfile:

# Codes for Gemfile
gem 'github-pages'
source 'https://rubygems.org'

Gemfile is created at the root of site and it instructs Gem to use github-pages providing latest version of dependencies used by GitHub.

Install bundle. While in the same directory (with Gemfile) run the following command from the Terminal window:

# Add the command in Terminal 
bundle install

It may take a while to run. If asked for permission sudo password, or run with sudo bundle install. If successfully installed, a message similar to shown below is displayed.

Bundle complete! 1 Gemfile dependency, 85 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.

Now that required applications Ruby, RubyGems and XCode Command Line and their dependencies (bundler, Gemfile) installed, we go ahead and install Jekyll.

5. Install jekyll

Following Tania Rascia’s Tutorial, install a new jekyll site named myjekyll in my-jekyll-site folder. Open the Terminal window and change directory to my-jekyll-site folder and issue following command:

# Install a new site named myjekyll
jekyll new myjekyll

New jekyll site installed in <PATH>

Tip: The new command instructs jekyll to install with its default theme minima on <PATH> i.e current location.

5.1. Initialize a new Git repository in the myjekyll folder. Move to the new directory (myjekyll):

# change directory to myjekyll folder
cd myjekyll

# Initialize a new GIT repository
git init

#OUTPUT message
Initialized empty Git repository in /Users/Desktop/my-jekyll-site/myjekyll/.git/

Tip: A git repository in local install is recommended if git is used to push site to remote server. The git init command creates a hidden empty .git repository. A hidden .git directory contains everything regarding this repository (eg. configuration, commit, history, hooks/folders and others) and example of shell scripts.

This completes our Jekyll site installation. Next, we will examine structure of files/folders briefly and view our jeckyll site in a browser.

Jeckyll File Structure & How It Works

File structure of a basic Jekyll site with default minima theme is found in the documentation. Lets examine the files/folder structure of our site which are shown below:

#File structure 
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _site
├── _posts
│   └── 2016-12-04-welcome-to-jekyll.markdown
├── about.md # => http://example.com/about.html
└── index.md # => http://example.com.index.htm

A brief description files/folders shown above are presented in the following table (Source: Jekyll Documentation Directory Structure).

File Directory Description
_config.yml Stores configuration data. Many of these options can be specified from the command line executable but it’s easier to specify them here so you don’t have to remember them.
_posts This is where blog posts usually written in Markdown are placed.
_site This is where the generated static site including all our assets in _site folder.
index.md This renders sites index page. It is essentially a post loop wrapped in base layout.
about.md This displays about page (eg. example.com/about.html).
Gemfile Contain information to inform Bundler about the gem requirements in the site.

Above table provides brief description of very basic file/folder structure. When we start modifying the sites by adding _page, _layout, _drafts, sass and other assets its file/folder structure changes too. A basic Jekyll site directory structure is shown here.

Lets understand how all this works. When we execute jekyll serve command in the our site folder using Terminal, the server goes through all the files and folders and serve our site into _site folder.

Running Jekyll Site

Issue jekyll serve command from Terminal window. From  project directory folder, issue following command in the Terminal window. If --watch command is added at the end, it will force Jekyll to rebuild the site every time file is saved.

#Issue serve command
jekyll serve

#issue command with watch
jekyll serve --watch

Jekyll comes with a build-in development server. The serve command runs a “watch” on the entire server (similar to Gulp or Grunt JavaScript task runner) and content files will be compiled into static HTML.When the message “Server running… press ctrl-c to stop” in displayed in the terminal,it is time to visit browser.

View Site in a Browser.  Add http://localhost:4000 address in a browser and check out the default Jekyll site. It should display a compiled default site as shown below:

Screen Shot of Jekyll generated site

Yes! we made it.Its a basic default site.

3. Start & Stop run. To stop server run issue CTRL + C command in the terminal which stop the running process and the site will not be served in the localhost. To run jekyll site generator again, issue jekyll serve command the server starts running and the site will be served to the localhost again.

What is Next

The site we created before was a basic out of the box with the default theme without any customization. Next we will continue building our site by adding blog posts, pages with customized templates, layout and other configuration & customization option available in Wiki Jekyll.

Next Post: Building a Static Site with Jekyll

Resources & Further Reading:

While preparing this post, I have referred the following references extensively. Please to refer original posts for more detailed information.