Jekyll CP Logo

 Improve this page

Troubleshooting

If you ever run into problems installing or using Jekyll, here are a few tips that might be of help. If the problem you’re experiencing isn’t covered below, please check out our other help resources as well.

Installation Problems

If you encounter errors during gem installation, you may need to install the header files for compiling extension modules for Ruby 2.0.0. This can be done on Ubuntu or Debian by running:

sudo apt-get install ruby2.0.0-dev

On Red Hat, CentOS, and Fedora systems you can do this by running:

sudo yum install ruby-devel

On NearlyFreeSpeech you need to run the following commands before installing Jekyll:

export GEM_HOME=/home/private/gems
export GEM_PATH=/home/private/gems:/usr/local/lib/ruby/gems/1.8/
export PATH=$PATH:/home/private/gems/bin
export RB_USER_INSTALL='true'

To install RubyGems on Gentoo:

sudo emerge -av dev-ruby/rubygems

On Windows, you may need to install RubyInstaller DevKit.

On Mac OS X, you may need to update RubyGems (using sudo only if necessary):

sudo gem update --system

If you still have issues, you can download and install new Command Line Tools (such as gcc) using the command

xcode-select --install

which may allow you to install native gems using this command (again using sudo only if necessary):

sudo gem install jekyll

Note that upgrading Mac OS X does not automatically upgrade Xcode itself (that can be done separately via the App Store), and having an out-of-date Xcode.app can interfere with the command line tools downloaded above. If you run into this issue, upgrade Xcode and install the upgraded Command Line Tools.

Jekyll & Mac OS X 10.11

With the introduction of System Integrity Protection, several directories that were previously writable are now considered system locations and are no longer available. Given these changes, there are a couple of simple ways to get up and running. One option is to change the location where the gem will be installed (again using sudo only if necessary):

sudo gem install -n /usr/local/bin jekyll

Alternatively, Homebrew can be installed and used to set up Ruby. This can be done as follows:

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Once Homebrew is installed, the second step is easy:

brew install ruby

Advanced users (with more complex needs) may find it helpful to choose one of a number of Ruby version managers (RVM, rbenv, chruby, etc.) in which to install Jekyll.

If you elect to use one of the above methods to install Ruby, it might be necessary to modify your $PATH variable using the following command:

export PATH=/usr/local/bin:$PATH

GUI apps can modify the $PATH as follows:

launchctl setenv PATH "/usr/local/bin:$PATH"

Either of these approaches are useful because /usr/local is considered a “safe” location on systems which have SIP enabled, they avoid potential conflicts with the version of Ruby included by Apple, and it keeps Jekyll and its dependencies in a sandboxed environment. This also has the added benefit of not requiring sudo when you want to add or remove a gem.

Could not find a JavaScript runtime. (ExecJS::RuntimeUnavailable)

This error can occur during the installation of jekyll-coffeescript when you don’t have a proper JavaScript runtime. To solve this, either install execjs and therubyracer gems, or install nodejs. Check out issue #2327 for more info.

Problems running Jekyll

On Debian or Ubuntu, you may need to add /var/lib/gems/1.8/bin/ to your path in order to have the jekyll executable be available in your Terminal.

Base-URL Problems

If you are using base-url option like:

jekyll serve --baseurl '/blog'

… then make sure that you access the site at:

http://localhost:4000/blog/index.html

It won’t work to just access:

http://localhost:4000/blog

Configuration problems

The order of precedence for conflicting configuration settings is as follows:

  1. Command-line flags
  2. Configuration file settings
  3. Defaults

That is: defaults are overridden by options specified in _config.yml, and flags specified at the command-line will override all other settings specified elsewhere.

Markup Problems

The various markup engines that Jekyll uses may have some issues. This page will document them to help others who may run into the same problems.

Liquid

The latest version, version 2.0, seems to break the use of {{ in templates. Unlike previous versions, using {{ in 2.0 triggers the following error:

'{{' was not properly terminated with regexp: /\}\}/  (Liquid::SyntaxError)

Excerpts

Since v1.0.0, Jekyll has had automatically-generated post excerpts. Since v1.1.0, Jekyll also passes these excerpts through Liquid, which can cause strange errors where references don’t exist or a tag hasn’t been closed. If you run into these errors, try setting excerpt_separator: "" in your _config.yml, or set it to some nonsense string.

Please report issues you encounter!

If you come across a bug, please create an issue on GitHub describing the problem and any work-arounds you find so we can document it here for others.