jekyll 0.12.1 → 1.0.0.beta1

data/site/_posts/2012-07-01-deployment-methods.md

@@ -0,0 +1,108 @@
+---
+layout: docs
+title: Deployment methods
+prev_section: github-pages
+next_section: contributing
+---
+
+Sites built using Jekyll can be deployed in a large number of ways due to the static nature of the generated output. A few of the most common deployment techniques are described below.
+
+## Web hosting providers (FTP)
+
+Just about any traditional web hosting provider will let you upload files to their servers over FTP. To upload a Jekyll site to a web host using FTP, simply run the `jekyll` command and copy the generated `_site` folder to the root folder of your hosting account. This is most likely to be the `httpdocs` or `public_html` folder on most hosting providers.
+
+### FTP using Glynn
+
+There is a project called [Glynn](https://github.com/dmathieu/glynn), which lets you easily generate your Jekyll powered website’s static files and
+send them to your host through FTP.
+
+## Self-managed web server
+
+If you have direct access yourself to the deployment web server yourself, the process is essentially the same, except you might have other methods available to you (such as `scp`, or even direct filesystem access) for transferring the files. Just remember to make sure the contents of the generated `_site` folder get placed in the appropriate web root directory for your web server.
+
+## Automated methods
+
+There are also a number of ways to easily automate the deployment of a Jekyll site. If you’ve got another method that isn’t listed below, we’d love it if you [contributed](../contributing) so that everyone else can benefit too.
+
+### Git post-update hook
+
+If you store your jekyll site in [Git](http://git-scm.com/) (you are using version control, right?), it’s pretty easy to automate the
+deployment process by setting up a post-update hook in your Git
+repository, [like
+this](http://web.archive.org/web/20091223025644/http://www.taknado.com/en/2009/03/26/deploying-a-jekyll-generated-site/).
+
+### Git post-receive hook
+
+To have a remote server handle the deploy for you every time you push changes using Git, you can create a user account which has all the public keys that are authorized to deploy in its `authorized_keys` file. With that in place, setting up the post-receive hook is done as follows:
+
+{% highlight bash %}
+laptop$ ssh deployer@myserver.com
+server$ mkdir myrepo.git
+server$ cd myrepo.git
+server$ git --bare init
+server$ cp hooks/post-receive.sample hooks/post-receive
+server$ mkdir /var/www/myrepo
+{% endhighlight %}
+
+Next, add the following lines to hooks/post-receive and be sure Jekyll is
+installed on the server:
+
+{% highlight bash %}
+GIT_REPO=$HOME/myrepo.git
+TMP_GIT_CLONE=$HOME/tmp/myrepo
+PUBLIC_WWW=/var/www/myrepo
+
+git clone $GIT_REPO $TMP_GIT_CLONE
+jekyll build $TMP_GIT_CLONE $PUBLIC_WWW
+rm -Rf $TMP_GIT_CLONE
+exit
+{% endhighlight %}
+
+Finally, run the following command on any users laptop that needs to be able to
+deploy using this hook:
+
+{% highlight bash %}
+laptops$ git remote add deploy deployer@myserver.com:~/myrepo.git
+{% endhighlight %}
+
+Deploying is now as easy as telling nginx or Apache to look at
+`/var/www/myrepo` and running the following:
+
+{% highlight bash %}
+laptops$ git push deploy master
+{% endhighlight %}
+
+### Rake
+
+Another way to deploy your Jekyll site is to use [Rake](https://github.com/jimweirich/rake), [HighLine](https://github.com/JEG2/highline), and
+[Net::SSH](http://net-ssh.rubyforge.org/). A more complex example of deploying Jekyll with Rake that deals with multiple branches can be found in [Git Ready](https://github.com/gitready/gitready/blob/en/Rakefile).
+
+### rsync
+
+Once you’ve generated the `_site` directory, you can easily rsync it using a `tasks/deploy` shell script similar to [this deploy script here](http://github.com/henrik/henrik.nyh.se/blob/master/tasks/deploy). You’d obviously need to change the values to reflect your site’s details. There is even [a matching TextMate command](http://gist.github.com/214959) that will help you run
+this script from within Textmate.
+
+
+## Rack-Jekyll
+
+[Rack-Jekyll](http://github.com/bry4n/rack-jekyll/) is an easy way to deploy your site on any Rack server such as Amazon EC2, Slicehost, Heroku, and so forth. It also can run with [shotgun](http://github.com/rtomakyo/shotgun/), [rackup](http://github.com/rack/rack), [mongrel](http://github.com/mongrel/mongrel), [unicorn](http://github.com/defunkt/unicorn/), and [others](https://github.com/adaoraul/rack-jekyll#readme).
+
+Read [this post](http://blog.crowdint.com/2010/08/02/instant-blog-using-jekyll-and-heroku.html) on how to deploy to Heroku using Rack-Jekyll.
+
+## Jekyll-Admin for Rails
+
+If you want to maintain Jekyll inside your existing Rails app, [Jekyll-Admin](http://github.com/zkarpinski/Jekyll-Admin) contains drop in code to make this possible. See Jekyll-Admin’s [README](http://github.com/zkarpinski/Jekyll-Admin/blob/master/README) for more details.
+
+## Amazon S3
+
+If you want to host your site in Amazon S3, you can do so with
+[jekyll-s3](https://github.com/laurilehmijoki/jekyll-s3) application. It will
+push your site to Amazon S3 where it can be served like any web server,
+dynamically scaling to almost unlimited traffic. This approach has the
+benefit of being about the cheapest hosting option available for
+low-volume blogs as you only pay for what you use.
+
+<div class="note">
+  <h5>ProTip™: Use GitHub Pages for zero-hassle Jekyll hosting</h5>
+  <p>GitHub Pages are powered by Jekyll behind the scenes, so if you’re looking for a zero-hassle, zero-cost solution, GitHub Pages are a great way to <a href="../github-pages">host your Jekyll-powered website for free</a>.</p>
+</div>

data/site/_posts/2012-07-01-extras.md

@@ -0,0 +1,103 @@
+---
+layout: docs
+title: Extras
+prev_section: plugins
+next_section: github-pages
+---
+
+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.
+
+## Pygments
+
+If you want syntax highlighting via the `{{ "{% highlight " }}%}` tag in your
+posts, you’ll need to install [Pygments](http://pygments.org/).
+
+### Installing Pygments on OSX
+
+Mac OS X (Leopard onwards) come preinstalled with Python, so on just about any OS X machine you can install Pygments simply by running:
+
+{% highlight bash %}
+sudo easy_install Pygments
+{% endhighlight %}
+
+#### Installing Pygments using Homebrew
+
+Alternatively, you can install Pygments with [Homebrew](http://mxcl.github.com/homebrew/), an excellent package manager for OS X:
+{% highlight bash %}
+brew install python
+# export PATH="/usr/local/share/python:${PATH}"
+easy_install pip
+pip install --upgrade distribute
+pip install pygments
+{% endhighlight %}
+
+**ProTip™**: Homebrew doesn’t symlink the executables for you. For the Homebrew default Cellar location and Python 2.7, be sure to add `/usr/local/share/python` to your `PATH`. For more information, check out [the Homebrew wiki](https://github.com/mxcl/homebrew/wiki/Homebrew-and-Python).
+
+#### Installing Pygments using MacPorts
+
+If you use MacPorts, you can install Pygments by running:
+
+{% highlight bash %}
+sudo port install python25 py25-pygments
+{% endhighlight %}
+
+Seriously though, you should check out [Homebrew](http://mxcl.github.com/homebrew/)—it’s awesome.
+
+
+### Installing Pygments on Arch Linux
+
+You can install Pygments using the pacman package manager as follows:
+
+{% highlight bash %}
+sudo pacman -S python-pygments
+{% endhighlight %}
+
+Or to use python2 for Pygments:
+{% highlight bash %}
+sudo pacman -S python2-pygments
+{% endhighlight %}
+
+### Installing Pygments on Ubuntu and Debian
+
+{% highlight bash %}
+sudo apt-get install python-pygments
+{% endhighlight %}
+
+### Installing Pygments on RedHat, Fedora, and CentOS
+
+{% highlight bash %}
+sudo yum install python-pygments
+{% endhighlight %}
+
+### Installing Pygments on Gentoo
+
+{% highlight bash %}
+sudo emerge -av dev-python/pygments
+{% endhighlight %}
+
+## LaTeX Support
+
+Maruku comes with optional support for LaTeX to PNG rendering via
+blahtex (Version 0.6) which must be in your `$PATH` along with `dvips`. If you need Maruku to not assume a fixed location for `dvips`, check out [Remi’s Maruku fork](http://github.com/remi/maruku).
+
+## RDiscount
+
+If you prefer to use [RDiscount](http://github.com/rtomayko/rdiscount) instead of [Maruku](http://maruku.rubyforge.org/) for markdown, just make sure you have it installed:
+
+{% highlight bash %}
+sudo gem install rdiscount
+{% endhighlight %}
+
+And then run Jekyll with the following option:
+
+{% highlight bash %}
+jekyll build --markdown rdiscount
+{% endhighlight %}
+
+Or, specify RDiscount as the markdown engine in your `_config.yml` file to have Jekyll run with that option by default (so you don’t have to specify the flag every time).
+
+{% highlight bash %}
+# In _config.yml
+markdown: rdiscount
+{% endhighlight %}
+

data/site/_posts/2012-07-01-frontmatter.md

@@ -0,0 +1,120 @@
+---
+layout: docs
+title: Front-matter
+prev_section: configuration
+next_section: posts
+---
+
+The front-matter is where Jekyll starts to get really cool. Any files that contain a [YAML](http://yaml.org/) front matter block will be processed by Jekyll as special files. The front matter must be the first thing in the file and must take the form of sets of variables and values set between triple-dashed lines. Here is a basic example:
+
+{% highlight yaml %}
+---
+layout: post
+title: Blogging Like a Hacker
+---
+{% endhighlight %}
+
+Between these triple-dashed lines, you can set predefined variables (see below for a reference) or even create custom ones of your own. These variables will then be available to you to access using Liquid tags both further down in the file and also in any layouts or includes that the page or post in question relies on.
+
+<div class="note warning">
+  <h5>UTF-8 Character Encoding Warning</h5>
+  <p>If you use UTF-8 encoding, make sure that no <code>BOM</code> 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.</p>
+</div>
+
+## Predefined Global Variables
+
+There are a number of predefined global variables that you can set in the front-matter of a page or post.
+
+<table>
+  <thead>
+    <tr>
+      <th>Variable</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p><code>layout</code></p>
+      </td>
+      <td>
+        <p>If set, this specifies the layout file to use. Use the layout file name without file extension. Layout files must be placed in the <code>_layouts</code> directory.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>permalink</code></p>
+      </td>
+      <td>
+        <p>If you need your processed URLs to be something other than the default <code>/year/month/day/title.html</code> then you can set this variable and it will be used as the final URL.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>published</code></p>
+      </td>
+      <td>
+        <p>Set to false if you don’t want a post to show up when the site is generated.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p style="margin-bottom: 5px;"><code>category</code></p>
+        <p><code>categories</code></p>
+      </td>
+      <td>
+        <p>Instead of placing posts inside of folders, you can specify one or more categories that the post belongs to. When the site is generated the post will act as though it had been set with these categories normally. Categories (plural key) can be specified as a <a href="http://en.wikipedia.org/wiki/YAML#Lists">YAML list</a> or a space-separated string.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>tags</code></p>
+      </td>
+      <td>
+        <p>Similar to categories, one or multiple tags can be added to a post. Also like categories, tags can be specified as a YAML list or a space-separated string.</p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+
+## Custom Variables
+
+Any variables in the front matter that are not predefined are mixed into
+the data that is sent to the Liquid templating engine during the
+conversion. For instance, if you set a title, you can use that in your
+layout to set the page title:
+
+{% highlight html %}
+<!DOCTYPE HTML>
+<html>
+  <head>
+    <title>{{ "{{ page.title " }}}}</title>
+  </head>
+  <body>
+    ...
+{% endhighlight %}
+
+## Predefined Variables for Posts
+
+These are available out-of-the-box to be used in the front-matter for a
+post.
+
+<table>
+  <thead>
+    <tr>
+      <th>Variable</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p><code>date</code></p>
+      </td>
+      <td>
+        <p>A date here overrides the date from the name of the post. This can be used to ensure correct sorting of posts.</p>
+      </td>
+    </tr>
+  </tbody>
+</table>

data/site/_posts/2012-07-01-github-pages.md

@@ -0,0 +1,34 @@
+---
+layout: docs
+title: GitHub Pages
+prev_section: extras
+next_section: deployment-methods
+---
+
+[GitHub Pages](https://pages.github.com) are public web pages for users, organizations, and repositories, that are freely hosted on [GitHub](https://github.com/). GitHub Pages are powered by Jekyll behind the scenes, so in addition to supporting regular HTML content, they’re also a great way to host your Jekyll-powered website for free.
+
+## Deploying Jekyll to GitHub Pages
+
+GitHub Pages work by looking at certain branches of repositories on GitHub. There are two basic types of Pages available, user/organization Pages and project Pages. The way to deploy these two types of pages are nearly identical, except for a few minor details.
+
+### User and Organization Pages
+
+User and organization Pages live in a special GitHub repository dedicated to only the Pages files. This repository must be named after the account name. For example, [@mojombo’s user page repository](https://github.com/mojombo/mojombo.github.com) has the name `mojombo.github.com`.
+
+Content from the `master` branch of your repository will be used to build and publish the GitHub Pages site, so make sure your Jekyll site is stored there.
+
+<div class="note info">
+  <h5>Custom domains do not affect repository names</h5>
+  <p>GitHub Pages are initially configured to live under the `username.github.com` subdomain, which is why repositories must be named this way <strong>even if a custom domain is being used</strong>.</p>
+</div>
+
+### Project Pages
+
+Unlike user and organization Pages, Project Pages are kept in the same repository as the project they are for, except that the website content is stored in a specially named `gh-pages` branch. The content of this branch will be used to rendered using Jekyll, and the output will become available under a subpath of your user pages subdomain, such as `username.github.com/project` (unless a custom domain is specified—see below).
+
+The Jekyll project repository itself is a perfect example of this branch structure—the [master branch](https://github.com/mojombo/jekyll) contains the actual software project for Jekyll, however the Jekyll website (that you’re looking at right now) is contained in the [gh-pages branch](https://github.com/mojombo/jekyll/tree/gh-pages) of the same repository.
+
+<div class="note">
+  <h5>GitHub Pages Documentation, Help, and Support</h5>
+  <p>For more information about what you can do with GitHub Pages, as well as for troubleshooting guides, you should check out <a href="https://help.github.com/categories/20/articles">GitHub’s Pages Help section</a>. If all else fails, you should contact <a href="https://github.com/contact">GitHub Support</a>.</p>
+</div>

data/site/_posts/2012-07-01-heroku.md

@@ -0,0 +1,8 @@
+---
+layout: docs
+title: Heroku
+prev_section: github-pages
+next_section: manual-deployment
+---
+
+Move along, people. Nothing to see here.

data/site/_posts/2012-07-01-home.md

@@ -0,0 +1,47 @@
+---
+layout: docs
+title: Welcome
+next_section: installation
+---
+
+This site aims to be a comprehensive guide to Jekyll. We’ll cover everything from getting your site up and running, creating and managing your content, customizing the way your site works and looks, deploying to various environments, as well as some advice on participating in the future development of Jekyll itself.
+
+## So what is Jekyll, exactly?
+
+Jekyll is a simple, blog-aware, static site generator. It takes a template directory containing raw text files in various formats, runs it through [Markdown](http://daringfireball.net/projects/markdown/) (or [Textile](http://textile.sitemonks.com/)) and [Liquid](http://liquidmarkup.org/) converters, and spits out a complete, ready-to-publish static website suitable for serving with your favorite web server. Jekyll also happens to be the engine behind [GitHub Pages](http://pages.github.com), which means you can use Jekyll to host your project’s page, blog, or website from GitHub’s servers **for free**.
+
+## Quick-start guide
+
+For the impatient, here's how to get Jekyll up and running.
+
+{% highlight bash %}
+~ $ gem install jekyll
+~ $ mkdir -p my/new/site
+~ $ cd my/new/site
+~ $ vim index.html
+~/my/new/site $ jekyll serve
+# => Now browse to http://localhost:4000
+{% endhighlight %}
+
+That's nothing though. The real magic happens when you start creating posts, using the front-matter to conrol templates and layouts, and taking advantage of all the awesome configuration options Jekyll makes available.
+
+## ProTips™, Notes, and Warnings
+
+Throughout this guide there are a number of small-but-handy pieces of information that can make using Jekyll easier, more interesting, and less hazardous. Here’s what to look out for.
+
+<div class="note">
+  <h5>ProTips™ help you get more from Jekyll</h5>
+  <p>These are tips and tricks that will help you be a Jekyll wizard!</p>
+</div>
+
+<div class="note info">
+  <h5>Notes are handy pieces of information</h5>
+  <p>These are for the extra tidbits sometimes necessary to understand Jekyll.</p>
+</div>
+
+<div class="note warning">
+  <h5>Warnings help you not blow things up</h5>
+  <p>Be aware of these messages if you wish to avoid certain death.</p>
+</div>
+
+If you come across anything along the way that we haven’t covered, or if you know of a tip yourself you think others would find handy, please [file an issue](https://github.com/mojombo/jekyll/issues/new) and we’ll see about including it in this guide.

data/site/_posts/2012-07-01-installation.md

@@ -0,0 +1,43 @@
+---
+layout: docs
+title: Installation
+prev_section: home
+next_section: usage
+---
+
+Getting Jekyll installed and ready-to-go should only take a few minutes. If it ever becomes a pain in the ass, you should [file an issue](https://github.com/mojombo/jekyll/issues/new) (or submit a pull request) about what might be a better way to do things.
+
+### Requirements
+
+Installing Jekyll is easy and straight-forward, but there’s a few requirements you’ll need to make sure your system has before you start.
+
+- [Ruby](http://www.ruby-lang.org/en/downloads/)
+- [RubyGems](http://rubygems.org/pages/download)
+- Linux, Unix, or Mac OS X
+
+<div class="note info">
+  <h5>Running Jekyll on Windows</h5>
+  <p>It is possible to get <a href="http://www.madhur.co.in/blog/2011/09/01/runningjekyllwindows.html">Jekyll running on Windows</a> however the official documentation does not support installation on Windows platforms.</p>
+</div>
+
+## Install with RubyGems
+
+The best way to install Jekyll is via
+[RubyGems](http://docs.rubygems.org/read/chapter/3). At the terminal prompt, simply run the following command to install Jekyll:
+
+{% highlight bash %}
+gem install jekyll
+{% endhighlight %}
+
+All Jekyll’s gem dependancies 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](../troubleshooting) page or [report an issue](https://github.com/mojombo/jekyll/issues/new) so the Jekyll community can improve the experience for everyone.
+
+## Optional Extras
+
+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 syntax highlighting of code snippets using [Pygments](http://pygments.org/), LaTeX support, and the use of alternative content rendering engines. Check out [the extras page](../extras) for more information.
+
+<div class="note">
+  <h5>ProTip™: Enable Syntax Highlighting</h5>
+  <p>If you’re the kind of person who is using Jekyll, then chances are you’ll definitely want to enable syntax highlighting using Pygments. You should really <a href="../extras">check out how to do that</a> before you go any further.</p>
+</div>
+
+Now that you’ve got everything installed, let’s get to work!