jekyll 0.12.1 → 1.0.0.beta1

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

@@ -0,0 +1,49 @@
+---
+layout: docs
+title: Resources
+prev_section: sites
+---
+
+Jekyll’s growing use is producing a wide variety of tutorials, frameworks, extensions, examples, and other resources that can be very helpful. Below is a collection of links to some of the most popular Jekyll resources.
+
+### Jekyll tips & tricks, and examples
+
+- [A simple way to add draft posts](https://gist.github.com/2870636)
+
+  No plugins required.
+
+- [Tips for working with GitHub Pages Integration](https://gist.github.com/2890453)
+
+  Code example reuse, and keeping documentation up to date.
+
+- [Use Simple Form to integrate a simple contact
+  form](http://getsimpleform.com/)
+- [JekyllBootstrap.com](http://jekyllbootstrap.com)
+
+  Provides detailed explanations, examples, and helper-code to make
+  getting started with Jekyll easier.
+
+### Tutorials
+
+#### Integrating Jekyll with Git
+
+- [Blogging with Git, Emacs and Jekyll](http://metajack.im/2009/01/23/blogging-with-git-emacs-and-jekyll/)
+- [Using Git to maintain your blog](http://matedriven.com.ar/2009/04/28/using-git-to-maintain-your-blog.html) (step by step guide)
+
+#### Other hacks
+
+- [Integrating Twitter with Jekyll](http://www.justkez.com/integrating-twitter-with-jekyll/)
+  > “Having migrated Justkez.com to be based on Jekyll, I was pondering how I might include my recent twitterings on the front page of the site. In the Wordpress world, this would have been done via a plugin which may or may not have hung the loading of the page, might have employed caching, but would certainly have had some overheads. … Not in Jekyll.”
+- [‘My Jekyll Fork’, by Mike West](http://mikewest.org/2009/11/my-jekyll-fork)
+  > “Jekyll is a well-architected throwback to a time before Wordpress, when men were men, and HTML was static. I like the ideas it espouses, and have made a few improvements to it’s core. Here, I’ll point out some highlights of my fork in the hopes that they see usage beyond this site.”
+- [‘About this Website’, by Carter Allen](http://cartera.me/2010/08/12/about-this-website/)
+  > “Jekyll is everything that I ever wanted in a blogging engine. Really. It isn’t perfect, but what’s excellent about it is that if there’s something wrong, I know exactly how it works and how to fix it. It runs on the your machine only, and is essentially an added”build" step between you and the browser. I coded this entire site in TextMate using standard HTML5 and CSS3, and then at the end I added just a few little variables to the markup. Presto-chango, my site is built and I am at peace with the world.”
+- [Generating a Tag Cloud in Jekyll](http://www.justkez.com/generating-a-tag-cloud-in-jekyll/)
+
+  A guide to implementing a tag cloud and per-tag content pages using Jekyll.
+
+- [Jekyll Extensions -= Pain](http://rfelix.com/2010/01/19/jekyll-extensions-minus-equal-pain/)
+
+  A way to [extend Jekyll](http://github.com/rfelix/jekyll_ext) without forking and modifying the Jekyll gem codebase and some [portable Jekyll extensions](http://wiki.github.com/rfelix/jekyll_ext/extensions) that can be reutilized and shared.
+
+- [Using your Rails layouts in Jekyll](http://numbers.brighterplanet.com/2010/08/09/sharing-rails-views-with-jekyll)

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

@@ -0,0 +1,28 @@
+---
+layout: docs
+title: Sites using Jekyll
+prev_section: troubleshooting
+next_section: resources
+---
+
+It’s interesting to see what designs and features others have come up
+with. Below are some Jekyll-powered blogs which were hand-picked for
+learning purposes.
+
+- [Tom Preston-Werner](http://tom.preston-werner.com/)
+    ([source](http://github.com/mojombo/mojombo.github.com))
+- [Nick Quaranto](http://quaran.to/)
+    ([source](https://github.com/qrush/qrush.github.com))
+- [Roger Chapman](http://rogchap.com/)
+    ([source](https://github.com/rogchap/rogchap.github.com))
+- [GitHub Official Teaching Materials](http://teach.github.com)
+    ([source](https://github.com/github/teach.github.com))
+- [Rasmus Andersson](http://rsms.me/)
+    ([source](https://github.com/rsms/rsms.github.com))
+- [Scott Chacon](http://schacon.github.com)
+    ([source](https://github.com/schacon/schacon.github.com))
+
+If you would like to explore more examples, you can find a list of sites
+and their sources on the ["Sites" page in the Jekyll wiki][jekyll-sites].
+
+[jekyll-sites]: https://github.com/mojombo/jekyll/wiki/Sites

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

@@ -0,0 +1,95 @@
+---
+layout: docs
+title: Directory structure
+prev_section: usage
+next_section: configuration
+---
+
+Jekyll at its core 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 more. This is all done through strictly editing files, and the web interface is the final product.
+
+A basic Jekyll site usually looks something like this:
+
+{% highlight bash %}
+.
+├── _config.yml
+├── _includes
+|   ├── footer.html
+|   └── header.html
+├── _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
+└── index.html
+{% endhighlight %}
+
+An overview of what each of these does:
+
+<table>
+  <thead>
+    <tr>
+      <th>File / Directory</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p><code>_config.yml</code></p>
+      </td>
+      <td>
+        <p>Stores <a href="../configuration">configuration</a> 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 remember them.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>_includes</code></p>
+      </td>
+      <td>
+        <p>These are the partials that can be mixed and matched by your _layouts and _posts to facilitate reuse.  The liquid tag <code>{{ "{% include file.ext " }}%}</code> can be used to include the partial in <code>_includes/file.ext</code>.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>_layouts</code></p>
+      </td>
+      <td>
+        <p>These are the templates which posts are inserted into. Layouts are chosen on a post-by-post basis in the <a href="../frontmatter">YAML front matter</a>, which is described in the next section. The liquid tag <code>{{ "{{ content " }}}}</code> is used to inject data onto the page.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>_posts</code></p>
+      </td>
+      <td>
+        <p>Your dynamic content, so to speak. The format of these files is important, as named as <code>YEAR-MONTH-DAY-title.MARKUP</code>. The <a href="../permalinks">permalinks</a> can be adjusted very flexibly for each post, but the date and markup language are determined solely by the file name.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>_site</code></p>
+      </td>
+      <td>
+        <p>This is where the generated site will be placed once Jekyll is done transforming it. It's probably a good idea to add this to your <code>.gitignore</code> file.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>index.html</code> and other HTML, Markdown, Textile files</p>
+      </td>
+      <td>
+        <p>Provided that the file has a <a href="../frontmatter">YAML Front Matter</a> section, it will be transformed by Jekyll. The same will happen for any <code>.html</code>, <code>.markdown</code>, <code>.md</code>, or <code>.textile</code> file in your site's root directory or directories not listed above.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p>Other Files/Folders</p>
+      </td>
+      <td>
+        <p>Every other directory and file except for those listed above—such as <code>css</code> and <code>images</code> folders, <code>favicon.ico</code> files, and so forth—will be transferred over verbatim to the generated site. There's plenty of <a href="../sites">sites already using Jekyll</a> if you're curious as to how they're laid out.</p>
+      </td>
+    </tr>
+  </tbody>
+</table>

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

@@ -0,0 +1,217 @@
+---
+layout: docs
+title: Templates
+prev_section: migrations
+next_section: permalinks
+---
+
+Jekyll uses the [Liquid](http://www.liquidmarkup.org/) templating language to process templates. All of the [standard Liquid tags and filters](http://wiki.github.com/shopify/liquid/liquid-for-designers) are supported, Jekyll even adds a few handy filters and tags of its own to make common tasks easier.
+
+## Filters
+
+<table>
+  <thead>
+    <tr>
+      <th>Description</th>
+      <th><span class="filter">Filter</span> and <span class="output">Output</span></th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p class='name'><strong>Date to XML Schema</strong></p>
+        <p>Convert a Date into XML Schema format.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{{ "{{ site.time | date_to_xmlschema " }}}}</code>
+        </p>
+        <p>
+          <code class='output'>2008-11-17T13:07:54-08:00</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>Date to String</strong></p>
+        <p>Convert a date to short format.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{{ "{{ site.time | date_to_string " }}}}</code>
+        </p>
+        <p>
+          <code class='output'>17 Nov 2008</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>Date to Long String</strong></p>
+        <p>Format a date to long format.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{{ "{{ site.time | date_to_long_string " }}}}</code>
+        </p>
+        <p>
+          <code class='output'>17 November 2008</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>XML Escape</strong></p>
+        <p>Escape some text for use in XML.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{{ "{{ page.content | xml_escape " }}}}</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>CGI Escape</strong></p>
+        <p>CGI escape a string for use in a URL. Replaces any special characters with appropriate %XX replacements.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{{ "{{ “foo,bar;baz?” | cgi_escape " }}}}</code>
+        </p>
+        <p>
+          <code class='output'>foo%2Cbar%3Bbaz%3F</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>Number of Words</strong></p>
+        <p>Count the number of words in some text.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{{ "{{ page.content | number_of_words " }}}}</code>
+        </p>
+        <p>
+          <code class='output'>1337</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>Array to Sentence</strong></p>
+        <p>Convert an array into a sentence. Useful for listing tags.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{{ "{{ page.tags | array_to_sentence_string " }}}}</code>
+        </p>
+        <p>
+          <code class='output'>foo, bar, and baz</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>Textilize</strong></p>
+        <p>Convert a Textile-formatted string into HTML, formatted via RedCloth</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{{ "{{ page.excerpt | textilize " }}}}</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>Markdownify</strong></p>
+        <p>Convert a Markdown-formatted string into HTML.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{{ "{{ page.excerpt | markdownify " }}}}</code>
+        </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+## Tags
+
+### Includes (Partials)
+
+If you have small page fragments that you wish to include in multiple
+places on your site, you can use the `include` tag.
+
+{% highlight ruby %}
+{{ "{% include sig.textile " }}%}
+{% endhighlight %}
+
+Jekyll expects all include files to be placed in an `_includes`
+directory at the root of your source dir. So this will embed the
+contents of `/path/to/your/site/_includes/sig.textile` into the calling
+file.
+
+### Code snippet highlighting
+
+Jekyll has built in support for syntax highlighting of [over 100
+languages](http://pygments.org/languages/) thanks to
+[Pygments](http://pygments.org/). In order to take advantage of this
+you’ll need to have Pygments installed, and the `pygmentize` binary must
+be in your `$PATH`. When you run Jekyll, make sure you run it with
+[Pygments enabled](../extras).
+
+To render a code block with syntax highlighting, surround your code as follows:
+
+{% highlight ruby %}
+{{ "{% highlight ruby " }}%}
+def foo
+  puts 'foo'
+end
+{{ "{% endhighlight " }}%}
+{% endhighlight %}
+
+The argument to the `highlight` tag (`ruby` in the example above) is the language identifier. To find the appropriate identifier to use for the language you want to highlight, look for the “short name” on the [Lexers page](http://pygments.org/docs/lexers/).
+
+#### Line numbers
+
+There is a second argument to `highlight` called `linenos` that is
+optional. Including the `linenos` argument will force the highlighted
+code to include line numbers. For instance, the following code block
+would include line numbers next to each line:
+
+{% highlight ruby %}
+{{ "{% highlight ruby linenos " }}%}
+def foo
+  puts 'foo'
+end
+{{ "{% endhighlight " }}%}
+{% endhighlight %}
+
+#### Stylesheets for syntax highlighting
+
+In order for the highlighting to show up, you’ll need to include a
+highlighting stylesheet. For an example stylesheet you can look at
+[syntax.css](http://github.com/mojombo/tpw/tree/master/css/syntax.css).
+These are the same styles as used by GitHub and you are free to use them
+for your own site. If you use linenos, you might want to include an
+additional CSS class definition for the `.lineno` class in `syntax.css` to
+distinguish the line numbers from the highlighted code.
+
+### Post URL
+
+If you would like to include a link to a post on your site, the `post_url` tag will generate the correct permalink URL for the post you specify.
+
+{% highlight bash %}
+{{ "{% post_url 2010-07-21-name-of-post " }}%}
+{% endhighlight %}
+
+There is no need to include the file extension when using the `post_url` tag.
+
+You can also use this tag to create a link to a post in Markdown as follows:
+
+{% highlight html %}
+[Name of Link]({{ "{% post_url 2010-07-21-name-of-post " }}%})
+{% endhighlight %}
+

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

@@ -0,0 +1,108 @@
+---
+layout: docs
+title: Troubleshooting
+prev_section: contributing
+next_section: sites
+---
+
+If you ever run into problems installing or using Jekyll, here’s a few tips that might be of help. If the problem you’re experiencing isn’t covered below, please [report an issue](https://github.com/mojombo/jekyll/issues/new) so the Jekyll community can make everyone’s experience better.
+
+## Installation Problems
+
+If you encounter errors during gem installation, you may need to install
+the header files for compiling extension modules for ruby 1.9.1. This
+can be done on Ubunutu or Debian by running:
+
+{% highlight bash %}
+sudo apt-get install ruby1.9.1-dev
+{% endhighlight %}
+
+On Red Hat, CentOS, and Fedora systems you can do this by running:
+
+{% highlight bash %}
+sudo yum install ruby-devel
+{% endhighlight %}
+
+On [NearlyFreeSpeech](http://nearlyfreespeech.net/) you need to run the command with the following environment variable:
+
+{% highlight bash %}
+RB_USER_INSTALL=true gem install jekyll
+{% endhighlight %}
+
+On OSX, you may need to update RubyGems:
+
+{% highlight bash %}
+sudo gem update --system
+{% endhighlight %}
+
+To install RubyGems on Gentoo:
+
+{% highlight bash %}
+sudo emerge -av dev-ruby/rubygems
+{% endhighlight %}
+
+On Windows, you may need to install [RubyInstaller
+DevKit](http://wiki.github.com/oneclick/rubyinstaller/development-kit).
+
+## Problems running Jekyll
+
+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.
+
+## Base-URL Problems
+
+If you are using base-url option like `jekyll serve --baseurl '/blog'` then make sure that you access the site at `http://localhost:4000/blog/index.html`. Just accessing `http://localhost:4000/blog` will not work.
+
+## Configuration problems
+
+
+The order of precedence for conflicting [configuration settings](../configuration) is as follows:
+
+1.  Command-line flags
+2.  Configuration file settings
+3.  Defaults
+
+That is: defaults are overridden by options specified in `_config.yml`, and flags specified at the command-line will override all other settings specified elsewhere.
+
+## Markup Problems
+
+The various markup engines that Jekyll uses may have some issues. This
+page will document them to help others who may run into the same
+problems.
+
+### Maruku
+
+If your link has characters that need to be escaped, you need to use
+this syntax:
+
+`![Alt text](http://yuml.me/diagram/class/[Project]->[Task])`
+
+If you have an empty tag, i.e. `<script src="js.js"></script>`, Maruku
+transforms this into `<script src="js.js" />`. This causes problems in
+Firefox and possibly other browsers and is [discouraged in
+XHTML.](http://www.w3.org/TR/xhtml1/#C_3) An easy fix is to put a space
+between the opening and closing tags.
+
+### RedCloth
+
+Versions 4.1.1 and higher do not obey the notextile tag. [This is a known
+bug](http://aaronqian.com/articles/2009/04/07/redcloth-ate-my-notextile.html)
+and will hopefully be fixed for 4.2. You can still use 4.1.9, but the
+test suite requires that 4.1.0 be installed. If you use a version of
+RedCloth that does not have the notextile tag, you may notice that
+syntax highlighted blocks from Pygments are not formatted correctly,
+among other things. If you’re seeing this just install 4.1.0.
+
+### Liquid
+
+The latest version, version 2.0, seems to break the use of `{{ "{{" }}` in
+templates. Unlike previous versions, using `{{ "{{" }}` in 2.0 triggers the
+following error:
+
+{% highlight bash %}
+'{{ "{{" }}' was not properly terminated with regexp: /\}\}/  (Liquid::SyntaxError)
+{% endhighlight %}
+
+<div class="note">
+  <h5>Please report issues you encounter!</h5>
+  <p>If you come across a bug, please <a href="https://github.com/mojombo/jekyll/issues/new">create an issue</a> on GitHub describing the problem and any work-arounds you find so we can document it here for others.</p>
+</div>