1. Preface
Jekyll was born out the desire to create a blog engine that would make it possible to write posts in my local text editor, version those posts with Git, and keep up with my desire to tweak the styles and layout of my site.
In other words, I wanted something that fit into my existing software development workflow and toolchain. Jekyll handles not only this case, but a wide variety of other situations that call for static site generation based on converted content and layout templates.
At its core, Jekyll is a text transformation engine. The concept behind the system is this: you give it text written in your favorite markup language, be that Markdown, Textile, or just plain HTML, and it churns that through a layout or series of layout files. Throughout that process you can tweak how you want the site URLs to look, what data gets displayed on the layout and much more.
If you’re looking for a simple, yet powerful solution to your blogging or static site needs, Jekyll may be just what you’ve been looking for.
1.1. What this book covers
Chapter 1, Quick Start covers installation, introduces the Jekyll command line interface, and runs through a quick example demonstrating the site generator, post generator and how to convert your Jekyll site into a static site.
Chapter 2, Directory Layout covers the various files and directories that comprise a Jekyll site.
Chapter 3, Tags and Filters
Chapter X, Deploying your Jekyll Site
Chapter X, Customizing Jekyll with Plugins
Chapter X, Migrating to Jekyll from your Existing Blog
Chapter X, Configuration Reference
2. Chapter 1: Quick Start
This chapter is designed to get you up and running with Jekyll as quickly as possible.
2.1. Installation
The best way to install Jekyll is via RubyGems:
gem install jekyll
This is all you need in order to get started with a basic Jekyll site. Some options require additional packages to be installed.
If you encounter errors during gem installation, you may need to install the header files for compiling extension modules for ruby 1.8:
sudo apt-get install ruby1.8-dev
sudo yum install ruby-devel
RB_USER_INSTALL=true gem install jekyll
If you encounter errors like Failed to build gem native extension on Windows you may need to install RubyInstaller DevKit.
2.1.1. LaTeX to PNG
Maruku comes with optional support for LaTeX to PNG rendering via blahtex (Version 0.6) which must be in your $PATH along with @dvips@.
(NOTE: "remi’s fork of Maruku":http://github.com/remi/maruku/tree/master does not assume a fixed location for @dvips@ if you need that fixed)
2.1.2. RDiscount
sudo gem install rdiscount
And run Jekyll with the following option:
jekyll --rdiscount
Or, in your @_config.yml@ file put the following so you don’t have to specify the flag:
markdown: rdiscount
2.1.3. Pygments
If you want syntax highlighting via the @{% highlight %}@ tag in your posts, you’ll need to install Pygments.
brew install pip && pip install pygments
sudo port install python25 py25-pygments
sudo easy_install Pygments
sudo pacman -S python-pygments
$ sudo pacman -S python2-pygments
|
Note
|
python2 pygments version creates a pygmentize2 executable, while Jekyll tries to find pygmentize. Either create a symlink # ln -s /usr/bin/pygmentize2 /usr/bin/pygmentize or use the python3 version. |
sudo apt-get install python-pygments
$ sudo emerge -av dev-python/pygments
2.2. Creating your First Site
Jekyll comes with a handy generator that will create a barebones skeleton site to help you get up and running in no time. Simply create an empty directory to contain your site, navigate to it, and run the generator command:
$ mkdir mysite $ cd mysite $ jekyll gen
Make sure the directory is empty or Jekyll will refuse to run. If everything was successful, you’ll be left with a complete, valid Jekyll site that’s ready to be converted into a static site.
To perform the conversion, make sure you’re in the root of your Jekyll site directory and run:
$ jekyll --server
If all goes well, you should get a few lines with information about config file detection, source and destination paths, and a success message.
The --server command line option fires up a simple web server that will serve the static site we just generated so that we can easily preview what it will look like once we deploy it to a production environment.
Open up your favorite web browser and navigate to:
http://localhost:4000
Congratulations! You have now successfully created and converted your first Jekyll site!
3. Chapter 2: Directory Layout
If you followed the Quick Start in the last chapter, you have a Jekyll site on your local machine. Let’s take a closer look at it and see what makes it tick. The file layout should look something like this:
. |-- _config.yml |-- _layouts | |-- default.html | `-- post.html |-- _posts | |-- 2007-10-29-why-every-programmer-should-play-nethack.textile | `-- 2009-04-26-barcamp-boston-4-roundup.textile |-- _site |-- images | `-- logo.png `-- index.html
Notice that some of the files and directories begin with an underscore. These have special meaning to Jekyll. The underscore ensures that they will not interfere with the rest of your site’s normal content. It also means that if any of your normal files start with an underscore, they will cause problems, so try to avoid this.
3.1. _config.yml
This file stores configuration data. A majority of these options can be specified from the command line executable but it’s easier to throw them in here so you don’t have to type them out every time. Detailed explanations of configuration directives can be found in Chapter X.
3.2. _layouts
Files in this directory represent templates that can be used to wrap converted pages. Layouts are defined on a page-by-page basis in the YAML front matter. The liquid tag {{ content }} specifies where the content will be placed during the conversion process.
3.3. _posts
If you’re using Jekyll as a blog engine, this is where you’ll place your blog posts. A post’s filename contains several pieces of data, so you must be very careful about how these files are named. The filename format is: YEAR-MONTH-DATE-SLUG.MARKUP. The YEAR must be four numbers and the MONTH and DATE must be two numbers each. The SLUG is what will appear in the URL. The MARKUP tells Jekyll the format of the post. The date and slug will be used along with any permalink options you specify (See Chapter X) to construct the final URL of the post.
3.4. _site
This is where the generated site will be placed (by default) once Jekyll is done transforming it. If you’re using version control, you’ll want to add this directory to the list of files to be ignored.
3.5. Normal Files with YAML Front Matter
All files outside of the special underscore directories and that do not themselves begin with an underscore will be scanned by Jekyll and subjected to conversion if they contain any YAML front matter.
3.6. Everything Else
Any files and directories that do not fall into one of the above categories will be copied to the static site as-is without modification. In this example, images/logo.png will be copied to the same location in the generated site.
h2. Running Jekyll
Usually this is done through the @jekyll@ executable, which is installed with the gem. In order to get a server up and running with your Jekyll site, run:
@jekyll --server@
and then browse to http://0.0.0.0:4000. There’s plenty of available to you as well.
On Debian or Ubuntu, you may need to add @/var/lib/gems/1.8/bin/@ to your path.
h2. Deployment