The Jekyll logo

The Jekyll logo

Jekyll is a free and open-source static site generator (SSG) that is written in Ruby and developed by GitHub. According to most sources it is the most popular free and open-source SSG available in the world today. It is the engine that powers this website and several others, most of which are hosted by GitHub Pages (GP). GitHub Pages enables users to create a website and maintain it in a GitHub repository. Using GP for hosting has several advantages, for one it is free, second it is possible to edit one’s website on GP from the command-line, from feature-packed text editors like Atom (also developed by GitHub) or even from the GitHub web interface. GP can be used with a number of different static site generators, the only other one, besides Jekyll, I have personally seen being used with GP is Hugo (a SSG written in Go), however.

The major advantage of SSGs over their dynamic site generator counterparts, is that they minimize the client-side burden for viewing the site, which means that users of smartphones are less likely to wait long periods to view the site. Jekyll as a SSG has a few different advantages and disadvantages, from my point of view its most significant advantage is that it is easy to learn and use and its most significant disadvantage is that it is difficult (but not impossible, for the patient) to run it on Microsoft Windows, due to its Ruby dependency. I have tried one other SSG, Hugo, which was a nightmare, in terms of how difficult it was to set up a site.

This post leaves out some advanced options mentioned in the official Jekyll documentation, partly because some of them I do not even understand, but also partly because I want this post to be simple enough to follow that even a twelve year old could follow these instructions without a problem.

Setup

The Hornery like most Jekyll-powered sites is hosted by GitHub Pages, this section covers how to set up your website with GitHub pages and assumes you already have a GitHub account. If you do not have a GitHub account merely go to the Home Page and fill out the form there.

The way I created The Hornery was by creating a GitHub repository with the name: username.github.io, where username was replaced by my username, fusion809. The next step requires that Jekyll be installed with RubyGems itself (even if Jekyll has already been installed with Bundle) on your computer. To do this run:

user $  gem install jekyll

then move onto this next step I speak of, by running:

user $  jekyll new username.github.io

this should create a new folder with the default layout of a Jekyll site in /home/username/username.github.io (assuming you ran this from your home directory and your PC username is the same as your GitHub username). Then change into this directory (user $  cd /home/username/username.github.io ) and run user $  git init (to install Git see the Getting the Dependencies below). Then configure your git remote to point to your GitHub repo. This means, for me at least, running something like:

user $  git remote add origin https://github.com/username/username.github.io

after this you will likely wish to edit your site’s _config.yml file, adding information about your site, further details can be found in the next section. After you think you are finished editing _config.yml I would recommend you run Jekyll locally by following the Bundle instructions outlined in this section, as this will tell you if there are any issues you need to fix with your Jekyll site and give you some hints as to where and what they might be. If no errors turn up then I would recommend you start making commits to your site’s Git repository with:

user $  git add --all
user $  git commit -m "Commit message"
user $  git push origin master

where, of course, "Commit message" is to be replaced with your actual commit message. Typing this out everytime one wishes to make a commit can get a little tedious and irritating so I would recommend adding this function to your ~/.bashrc file:

and then sourcing this file with source ~/.bashrc. This way whenever you want to make a commit merely type push "Commit message" inside a terminal window running Bash.

Configuring Jekyll

Jekyll’s main configuration file is _config.yml. In it there are several pieces of information about the website, like its title, as well as its associated email address, Facebook, GitHub and Twitter accounts. It also lists the Rubygems it needs besides the default set used by all Jekyll sites, along with what markdown parser is to be used by the site and the various extensions for said rendering engine that is required. Here is an example _config.yml (it is the one being used by The Hornery as of 25 January 2016) file:

In this example the markdown parser being used is Redcarpet, while the Redcarpet extensions being loaded are listed on lines 32 to 45. The additional gems being used are jekyll-redirect-from and jekyll-last-modified-at. If you want to add extra gems to your site you will need to also add them to Gemfile, via adding the line gem 'gem_name' where, of course, 'gem_name' is the gem’s name. After this you will also have to run Bundle install to install these gems.

Further information on Jekyll configuration can be found here.

Running Locally

If you are interested in setting up Jekyll locally on your Linux machine here is a Bash script that can do this for you (run this as standard, non-root user, from the top-level directory of the local copy of your Jekyll site), provided that RubyGems has already been installed on your Linux system (for instructions on installing RubyGems see the section below):

user $  gem install bundler
user $  bundle install

then to start Jekyll locally run: user $  bundle exec jekyll serve . When I used this method of starting Jekyll I defined the Bash function jekex in my ~/.bashrc file with contents of bundle exec jekyll serve. At the moment this will install Jekyll 2.4.0, while the latest version (which is run by GitHub pages) is 3.1.0. Running Jekyll locally gives debugging information, whenever any errors are countered which can be invaluable, it also gives you the opportunity to preview your site before you push any commits to your site’s Git repository. When Jekyll is run through Bundler it starts the Jekyll server at http://0.0.0.0:4000, so to preview your Jekyll site you would have to open up to http://0.0.0.0:4000.

I have also managed to install Jekyll 3.1.0 and run it locally, without having to run bundle exec before executing any Jekyll commands line jekyll serve. If you would like to do this yourself, I suggest you copy my Gemfile:

and this line from my _config.yml:

After this I suggest you run user $  bundle update jekyll and user $  bundle install . Jekyll 3.1.0, by default, does not build posts who’s publish date is later than the current date, and quite often I give my posts that I am presently working on the publish date I expect them to be ready on. To overcome this issue I have used this modified jekex function: jekyll serve --future. The --future causes future posts to be built. Note I can run jekyll serve with 3.1.0 without a problem, while running this same command with the default version of Jekyll, 2.4.0, fails, giving out errors. I think the reason why Bundler uses Jekyll 2.4.0 by default is because it is more stable than later versions like 3.1.0, but it is also slower to regenerate file changes.

Dependencies

There are two package dependencies for Jekyll that should be installed with one’s package manager, Git and RubyGems. This section covers how to install them with the most popular Linux package managers.

APT

Used by:
  • antiX
  • Bodhi Linux
  • Debian
  • Deepin
  • elementary OS
  • Kali Linux
  • Linux Lite
  • Linux Mint
  • LXLE
  • PCLinuxOS
  • Tails
  • Ubuntu
  • Zorin OS


user $  sudo apt-get install git ruby

or:

root #  apt-get install git ruby

DNF

Used by:
  • Chapeau
  • Fedora
  • Korora


user $  sudo dnf install git ruby

or:

root #  dnf install git ruby

Entropy

Used by:
  • Sabayon
  • Spike


user $  sudo equo i -av dev-vcs/git dev-ruby/rubygems

or:

root #  equo i -av dev-vcs/git dev-ruby/rubygems

pacman

Used by:
  • Arch Linux
  • Antergos
  • ArchBang
  • Chakra GNU/Linux
  • Manjaro Linux
  • Parabola GNU/Linux-libre


user $  sudo pacman -S git rubygems

or:

root #  pacman -S git rubygems

Portage

Used by:
  • Calculate Linux
  • Gentoo Linux
  • Sabayon


user $  sudo emerge -av dev-vcs/git dev-ruby/rubygems

or:

root #  emerge -av dev-vcs/git dev-ruby/rubygems

urpmi

Used by:
  • Mageia
  • OpenMandriva LX


user $  sudo urpmi git ruby-RubyGems

or:

root #  urpmi git ruby-RubyGems

yum

Used by:
  • CentOS
  • Oracle Linux
  • Red Hat Enterprise Linux
  • Scientific Linux


user $  sudo yum install git ruby

or:

root #  yum install git ruby

ZYpp

Used by:
  • openSUSE
  • SUSE Linux Enterprise


user $  sudo zypper in git ruby

or:

root #  zypper in git ruby

Vendor Folder

Running bundle install will create a folder called vendor inside your Jekyll site. This directory contains gems (the package format used by RubyGems) and they can take up a large amount of space in your Jekyll site. Consequently you may wish to edit your .gitignore file to include this vendor folder (to see how to do this you are welcome to look at this repository’s .gitignore file) so as to save space on your Jekyll site, it is important to do this before making any commits.

Handling Errors

If this returns errors then my guess is that your Gemfile and _config.yml files, which should both be in the top-level directory of your Jekyll site, are incorrectly written or you have made some syntactic error in the Liquid tags on your website. Including Liquid tags that are not defined is known to return errors like:

where in this example, 'last_modified_at' is the name of the undefined tag in this case and _posts/2015-11-26-bash-scripting-and-the-command-line-an-introduction-for-sabayon-users.md/#excerpt is where the undefined tag is included in the website. Likewise if Liquid tags (like {% include %}) are not properly ended (in this example they may not be correctly ended with a %}, giving {% include }) it can return errors like:

. While if you include a file that does not exist you will get this error:

where {% include_relative SS/table2-builtins.html %} appeared in the _post/SS/syntax.md, which in turn was included (by use of the line {% include_relative SS/syntax.md %} in _posts/2016-01-30-shell-scripting-and-the-command-line-an-introduction.md and the error shown is because the file _post/SS/table2-builtins.html does not exist.

Directory Structure

Jekyll sites have the following directory structure:

where () are optional folders (some of which like _data, images and js are ones The Hornery uses, but are not widely used by Jekyll sites in general) or files that are not included by default, {} denotes folders or files generated by Bundler and [] denotes folders or files I would recommend is listed in .gitignore. Further details on this can be found in the official documentation here.

Writing Posts

_posts is the folder in which one’s completed posts go, while _drafts is where one’s draft posts go. Here is the official documentation on writing posts. Here is the official documentation on working with drafts. By default Jekyll does not build drafts, unless the --drafts switch is passed to the jekyll serve command. In other words, if you use Bundler to run Jekyll, like I outlined in the Running Jekyll Locally section, the command you should run to build the drafts too is:

user $  bundle exec jekyll serve --drafts

posts (both completed and drafts) can be written in markdown or HTML, by default, although with the use of extra extensions it is possible for Jekyll to work with textfile and other post formats. Regardless of what file format is used for posts, however, all completed posts in the _posts folder must have the name format: YEAR-MONTH-DAY-title.MARKUP where .MARKUP is dependent on the post’s file extension (e.g., it could take the form .md for markdown posts), while YEAR-MONTH-DAY should be the date the post is published and title should be the post’s title, delimitered by dashes (-). All of these are overridden by the YAML front matter’s values.

All posts should include the YAML front matter, which is explained in greater detail here. It is essentially all the metadata for your post, like the date it is published, its title, its layout (which must appear in the _layouts) folder, etc. and appears at the start of the post. As previously mentioned if they conflict with the date the post was published and its title as provided by the post’s file name, the values in the YAML front matter will be used instead.

Editing

<i>The Hornery</i> opened in Atom 1.4.0

The Hornery opened in Atom 1.4.0

Jekyll sites are essentially just GitHub repositories that contain several markup and source code files that can be edited in any text editor or through GitHub’s web-based interface. The way I edit The Hornery is by Git cloning its repository, editing its markup and source code files with Atom and then committing any changes upstream with Git, after first testing for errors by running Jekyll locally. Jekyll sites can also be edited from the command-line with GNU nano or Vim, although one would still need commit any changes upstream with Git. I use the push function to push these changes upstream.

External Resources

Comments