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