Note: The book edition is still an early release and a work-in-progess.
This is the (official) documentation for the Jekyll static site builder / generator reformatted in a single-page book edition.
See the source repo for how the book gets auto-built with "plain" Jekyll - of course - and hosted on GitHub Pages.
Questions? Comments? Send them to the Jekyll Talk forum post titled Jekyll Docu Reformatted as a Single-Page in Black 'n' White (Book Version) - Why? Why Not?.
Thanks to all Jekyll contributors for making it all possible.
Getting Jekyll installed and ready-to-go should only take a few minutes. If it ever becomes a pain, please file an issue (or submit a pull request) describing the issue you encountered and how we might make the process easier
Installing Jekyll is easy and straight-forward, but there are a few requirements you’ll need to make sure your system has before you start.
While Windows is not officially supported, it is possible to get it running on Windows. Special instructions can be found on our Windows-specific docs page.
The best way to install Jekyll is via RubyGems. At the terminal prompt, simply run the following command to install Jekyll:
All of Jekyll’s gem dependencies are automatically installed by the above command, so you won’t have to worry about them at all. If you have problems installing Jekyll, check out the troubleshooting page or report an issue so the Jekyll community can improve the experience for everyone.
If you run into issues installing Jekyll's dependencies which make use of
native extensions and are using Mac OS X, you will need to install Xcode
and the Command-Line Tools it ships with. Download in
Preferences → Downloads → Components.
In order to install a pre-release, make sure you have all the requirements installed properly and run:
This will install the latest pre-release. If you want a particular pre-release,
-v switch to indicate the version you’d like to install:
If you’d like to install a development version of Jekyll, the process is a bit more involved. This gives you the advantage of having the latest and greatest, but may be unstable.
There are a number of (optional) extra features that Jekyll supports that you may want to install, depending on how you plan to use Jekyll. These extras include LaTeX support, and the use of alternative content rendering engines. Check out the extras page for more information.
If you’re the kind of person who is using Jekyll, then chances are you’ll want to enable syntax highlighting using Pygments or Rouge. You should really check out how to do that before you go any farther.
Now that you’ve got everything installed, let’s get to work!
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.
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:
On Red Hat, CentOS, and Fedora systems you can do this by running:
On NearlyFreeSpeech you need to run the following commands before installing Jekyll:
To install RubyGems on Gentoo:
On Windows, you may need to install RubyInstaller DevKit.
On Mac OS X, you may need to update RubyGems (using
sudo only if necessary):
If you still have issues, you can download and install new Command Line
Tools (such as
gcc) using the command
which may allow you to install native gems using this command (again using
sudo only if necessary):
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.
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):
Alternatively, Homebrew can be installed and used to set up Ruby. This can be done as follows:
Once Homebrew is installed, the second step is easy:
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:
GUI apps can modify the
$PATH as follows:
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.
This error can occur during the installation of
therubyracer gems, or install
nodejs. Check out
issue #2327 for more info.
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.
While Windows is not an officially-supported platform, it can be used to run Jekyll with the proper tweaks. This page aims to collect some of the general knowledge and lessons that have been unearthed by Windows users.
Alternatively David Burela has written instructions on how to install Jekyll via Chocolately with 3 command prompt entries
If you use UTF-8 encoding, make sure that no
characters exist in your files or very, very bad things will happen to
Jekyll. This is especially relevant if you’re running Jekyll on Windows.
Additionally, you might need to change the code page of the console window to UTF-8 in case you get a “Liquid Exception: Incompatible character encoding” error during the site generation process. It can be done with the following command:
As of v1.3.0, Jekyll uses the
listen gem to watch for changes when the
--watch switch is specified during a build or serve. While
built-in support for UNIX systems, it requires an extra gem for compatibility
with Windows. Add the following to the Gemfile for your site: