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
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 #OUTPUT ruby 2.3.3p222 (2016-11-21 revision 56859) [universal.x86_64-darwin17] #Check Ruby Gem installation gem -v #OUTPUT 2.5.2
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 #OUTPUT clang: error: no input files #Install Xcode xcode-select --install #OUTPUT 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
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.
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
4. Create Gemfile & Install Budle
# Codes for Gemfile gem 'github-pages' source 'https://rubygems.org'
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.
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 #OUTPUT New jekyll site installed in <PATH> #/Users/Desktop/my-jekyll-site/myjekyll
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 ├── 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).
||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.|
||This is where blog posts usually written in Markdown are placed.|
||This is where the generated static site including all our assets in
||This renders sites index page. It is essentially a post loop wrapped in base layout.|
||This displays about page (eg. example.com/about.html).|
||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
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
Running Jekyll Site
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
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:
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.