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?.
Onwards.
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:
$ gem install jekyllAll 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:
gem install jekyll --preThis will install the latest pre-release. If you want a particular pre-release,
use the -v switch to indicate the version you’d like to install:
gem install jekyll -v '2.0.0.alpha.1'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.
$ git clone git://github.com/jekyll/jekyll.git
$ cd jekyll
$ script/bootstrap
$ bundle exec rake build
$ ls pkg/*.gem | head -n 1 | xargs gem install -lThere 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:
sudo apt-get install ruby2.0.0-devOn Red Hat, CentOS, and Fedora systems you can do this by running:
sudo yum install ruby-develOn 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/rubygemsOn 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 --systemIf you still have issues, you can download and install new Command Line
Tools (such as gcc) using the command
xcode-select --installwhich may allow you to install native gems using this command (again using
sudo only if necessary):
sudo gem install jekyllNote 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):
sudo gem install -n /usr/local/bin jekyllAlternatively, 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 rubyAdvanced 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:$PATHGUI 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.
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.
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.
Julian Thilo has written up instructions to get Jekyll running on Windows and it seems to work for most. The instructions were written for Ruby 2.0.0, but should work for later versions prior to 2.2.
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 BOM header
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:
$ chcp 65001As 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 listen has
built-in support for UNIX systems, it requires an extra gem for compatibility
with Windows. Add the following to the Gemfile for your site:
gem 'wdm', '~> 0.1.0' if Gem.win_platform?