jekyll 1.0.2 → 1.0.3

data/site/docs/installation.md

@@ -50,10 +50,8 @@ community can improve the experience for everyone.
 
 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.
+include 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>

data/site/docs/migrations.md

@@ -15,12 +15,13 @@ the foreign system.
 ## Preparing for migrations
 
 Because the importers have many of their own dependencies, they are made
-available via a separate gem called `jekyll-import`. To use them, all you need
-to do is install the gem, and they will become available as part of Jekyll's
-standard command line interface.
+available via a separate gem called
+[`jekyll-import`](https://github.com/jekyll/jekyll-import). To use them, all
+you need to do is install the gem, and they will become available as part of
+Jekyll's standard command line interface.
 
 {% highlight bash %}
-$ gem install jekyll-import
+$ gem install jekyll-import --pre
 {% endhighlight %}
 
 You should now be all set to run the importers below. If you ever get stuck, you
@@ -55,13 +56,13 @@ Next, export your blog using the Wordpress export utility. Assuming that the
 exported file is saved as `wordpress.xml`, here is the command you need to run:
 
 {% highlight bash %}
-$ ruby -rubygems -e 'require "jekyll/migrators/wordpressdotcom";
-    Jekyll::WordpressDotCom.process("wordpress.xml")'
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/wordpressdotcom";
+    JekyllImport::WordpressDotCom.process("wordpress.xml")'
 {% endhighlight %}
 
 <div class="note">
   <h5>ProTip™: Wordpress.com Export Tool</h5>
-  <p>If you are migrating from a Wordpress.com account, you can access the export tool at the following URL: `https://YOUR-USER-NAME.wordpress.com/wp-admin/export.php`.</p>
+  <p markdown="1">If you are migrating from a Wordpress.com account, you can access the export tool at the following URL: `https://YOUR-USER-NAME.wordpress.com/wp-admin/export.php`.</p>
 </div>
 
 ### Using Wordpress MySQL server connection
@@ -69,8 +70,8 @@ $ ruby -rubygems -e 'require "jekyll/migrators/wordpressdotcom";
 If you want to import using a direct connection to the Wordpress MySQL server, here's how:
 
 {% highlight bash %}
-$ ruby -rubygems -e 'require "jekyll/migrators/wordpress";
-    Jekyll::WordPress.process("database", "user", "pass")'
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/wordpress";
+    JekyllImport::WordPress.process("database", "user", "pass")'
 {% endhighlight %}
 
 If you are using Webfaction and have to set up an [SSH
@@ -80,8 +81,8 @@ your access based on `localhost` and `127.0.0.1` not being equivalent in its
 authentication system:
 
 {% highlight bash %}
-$ ruby -rubygems -e 'require "jekyll/migrators/wordpress";
-    Jekyll::WordPress.process("database", "user", "pass", "127.0.0.1")'
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/wordpress";
+    JekyllImport::WordPress.process("database", "user", "pass", "127.0.0.1")'
 {% endhighlight %}
 
 ### Further Wordpress migration alternatives
@@ -104,29 +105,38 @@ might be useful to you:
 
 ## Drupal
 
-If you’re migrating from [Drupal](http://drupal.org), there is [a
-migrator](https://github.com/mojombo/jekyll/blob/master/lib/jekyll/migrators/drupal.rb)
-for you too:
+If you’re migrating from [Drupal](http://drupal.org), there are two migrators
+for you, depending upon your Drupal version:
+- [Drupal 6](https://github.com/jekyll/jekyll-import/blob/v0.1.0.beta1/lib/jekyll/jekyll-import/drupal6.rb)
+- [Drupal 7](https://github.com/jekyll/jekyll-import/blob/v0.1.0.beta1/lib/jekyll/jekyll-import/drupal7.rb)
 
 {% highlight bash %}
-$ ruby -rubygems -e 'require "jekyll/migrators/drupal";
-    Jekyll::Drupal.process("database", "user", "pass")'
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/drupal6";
+    JekyllImport::Drupal6.process("dbname", "user", "pass")'
+# ... or ...
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/drupal7";
+    JekyllImport::Drupal7.process("dbname", "user", "pass")'
 {% endhighlight %}
 
-<div class="note warning">
-  <h5>Warning: Drupal Version Compatibility</h5>
-  <p>This migrator was written for Drupal 6.1 and may not work as expected with
-  newer versions of Drupal. Please update it and send us a pull request if
-  necessary.</p>
-</div>
+If you are connecting to a different host or need to specify a table prefix for
+your database, you may optionally add those two parameters to the end of either
+Drupal migrator execution:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/drupal6";
+    JekyllImport::Drupal6.process("dbname", "user", "pass", "host", "table_prefix")'
+# ... or ...
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/drupal7";
+    JekyllImport::Drupal7.process("dbname", "user", "pass", "host", "table_prefix")'
+{% endhighlight %}
 
 ## Movable Type
 
 To import posts from Movable Type:
 
 {% highlight bash %}
-$ ruby -rubygems -e 'require "jekyll/migrators/mt";
-    Jekyll::MT.process("database", "user", "pass")'
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/mt";
+    JekyllImport::MT.process("database", "user", "pass")'
 {% endhighlight %}
 
 ## Typo
@@ -134,8 +144,8 @@ $ ruby -rubygems -e 'require "jekyll/migrators/mt";
 To import posts from Typo:
 
 {% highlight bash %}
-$ ruby -rubygems -e 'require "jekyll/migrators/typo";
-    Jekyll::Typo.process("database", "user", "pass")'
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/typo";
+    JekyllImport::Typo.process("database", "user", "pass")'
 {% endhighlight %}
 
 This code has only been tested with Typo version 4+.
@@ -145,8 +155,8 @@ This code has only been tested with Typo version 4+.
 To import posts from TextPattern:
 
 {% highlight bash %}
-$ ruby -rubygems -e 'require "jekyll/migrators/textpattern";
-    Jekyll::TextPattern.process("database_name", "username", "password", "hostname")'
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/textpattern";
+    JekyllImport::TextPattern.process("database_name", "username", "password", "hostname")'
 {% endhighlight %}
 
 You will need to run the above from the parent directory of your `_import`
@@ -161,15 +171,15 @@ sticky.
 To import posts from Mephisto:
 
 {% highlight bash %}
-$ ruby -rubygems -e 'require "jekyll/migrators/mephisto";
-    Jekyll::Mephisto.process("database", "user", "password")'
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/mephisto";
+    JekyllImport::Mephisto.process("database", "user", "password")'
 {% endhighlight %}
 
 If your data is in Postgres, you should do this instead:
 
 {% highlight bash %}
-$ ruby -rubygems -e 'require "jekyll/migrators/mephisto";
-    Jekyll::Mephisto.postgres({:database => "database", :username=>"username", :password =>"password"})'
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/mephisto";
+    JekyllImport::Mephisto.postgres({:database => "database", :username=>"username", :password =>"password"})'
 {% endhighlight %}
 
 ## Blogger (Blogspot)
@@ -196,16 +206,16 @@ alternatives:
 To import posts from your primary Posterous blog:
 
 {% highlight bash %}
-$ ruby -rubygems -e 'require "jekyll/migrators/posterous";
-    Jekyll::Posterous.process("my_email", "my_pass")'
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/posterous";
+    JekyllImport::Posterous.process("my_email", "my_pass")'
 {% endhighlight %}
 
 For any other Posterous blog on your account, you will need to specify the
 `blog_id` for the blog:
 
 {% highlight bash %}
-$ ruby -rubygems -e 'require "jekyll/migrators/posterous";
-    Jekyll::Posterous.process("my_email", "my_pass", "blog_id")'
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/posterous";
+    JekyllImport::Posterous.process("my_email", "my_pass", "blog_id")'
 {% endhighlight %}
 
 There is also an [alternative Posterous
@@ -217,30 +227,19 @@ that maintains permalinks and attempts to import images too.
 To import posts from Tumblr:
 
 {% highlight bash %}
-$ ruby -rubygems -e 'require "jekyll/migrators/tumblr";
-    Jekyll::Tumblr.process("http://www.your_blog_url.com", true)'
-{% endhighlight %}
-
-There is also [a modified Tumblr
-migrator](https://github.com/stephenmcd/jekyll/blob/master/lib/jekyll/migrators/tumblr.rb)
-that exports posts as Markdown and preserves post tags.
-
-The migrator above requires the `json` gem and Python's `html2text` to be
-installed as follows:
-
-{% highlight bash %}
-$ gem install json
-$ pip install html2text
-{% endhighlight %}
-
-Once installed, simply use the format argument:
-
-{% highlight bash %}
-$ ruby -rubygems -e 'require "jekyll/migrators/tumblr";
-    Jekyll::Tumblr.process("http://www.your_blog_url.com", format="md")'
+$ ruby -rubygems -e 'require "jekyll/jekyll-import/tumblr";
+    JekyllImport::Tumblr.process(url, format, grab_images, add_highlights, rewrite_urls)'
+# url    - String: your blog's URL
+# format - String: the output file extension. Use "md" to have your content
+#          converted from HTML to Markdown. Defaults to "html".
+# grab_images    - Boolean: whether to download images as well. Defaults to false.
+# add_highlights - Boolean: whether to wrap code blocks (indented 4 spaces) in a Liquid
+                   "highlight" tag. Defaults to false.
+# rewrite_urls   - Boolean: whether to write pages that redirect from the old Tumblr paths
+                   to the new Jekyll paths. Defaults to false.
 {% endhighlight %}
 
 ## Other Systems
 
 If you have a system for which there is currently no migrator, consider writing
-one and sending us a pull request.
+one and sending us [a pull request](https://github.com/jekyll/jekyll-import).

data/site/docs/plugins.md

@@ -404,6 +404,7 @@ There are a few useful, prebuilt plugins at the following locations:
 - [jekyll-rendering](https://github.com/blackwinter/jekyll-rendering): Jekyll plugin to provide alternative rendering engines.
 - [jekyll-pagination](https://github.com/blackwinter/jekyll-pagination): Jekyll plugin to extend the pagination generator.
 - [jekyll-tagging](https://github.com/pattex/jekyll-tagging): Jekyll plugin to automatically generate a tag cloud and tag pages.
+- [jekyll-contentblocks](https://github.com/rustygeldmacher/jekyll-contentblocks): Lets you use Rails-like content_for tags in your templates, for passing content from your posts up to your layouts.
 - [Generate YouTube Embed (tag)](https://gist.github.com/1805814) by [joelverhagen](https://github.com/joelverhagen): Jekyll plugin which allows you to embed a YouTube video in your page with the YouTube ID. Optionally specify width and height dimensions. Like “oEmbed Tag” but just for YouTube.
 - [JSON Filter](https://gist.github.com/1850654) by [joelverhagen](https://github.com/joelverhagen): filter that takes input text and outputs it as JSON. Great for rendering JavaScript.
 - [jekyll-beastiepress](https://github.com/okeeblow/jekyll-beastiepress): FreeBSD utility tags for Jekyll sites.
@@ -426,6 +427,8 @@ There are a few useful, prebuilt plugins at the following locations:
 - [File compressor](https://gist.github.com/2758691) by [mytharcher](https://github.com/mytharcher): Compress HTML (\*.html) and JavaScript(\*.js) files when output.
 - [smilify](https://github.com/SaswatPadhi/jekyll_smilify) by [SaswatPadhi](https://github.com/SaswatPadhi): Convert text emoticons in your content to themeable smiley pics. [Demo](http://saswatpadhi.github.com/)
 - [excerpts](http://blog.darkrefraction.com/2012/jekyll-excerpt-plugin.html) by [drawoc](https://github.com/drawoc): provides a nice way to implement page excerpts.
+- [jekyll-minibundle](https://github.com/tkareine/jekyll-minibundle): Asset bundling and cache busting using external minification tool of your choice, no gem dependencies.
+- [JekyllGalleryTag](https://github.com/redwallhp/JekyllGalleryTag) by [redwallhp](https://github.com/redwallhp): Generates thumbnails from a directory of images and displays them in a grid with a Liquid tag.
 
 <div class="note info">
   <h5>Jekyll Plugins Wanted</h5>

data/site/docs/posts.md

@@ -113,11 +113,33 @@ Of course, you have full control over how (and where) you display your posts,
 and how you structure your site. You should read more about [how templates
 work](../templates) with Jekyll if you want to know more.
 
+## Post excerpts
+
+Each post automatically takes the first block of text, from the beginning of the content
+to the first occurrence of `excerpt_separator`, and sets it as the `post.excerpt`.
+Take the above example of an index of posts. Perhaps you want to include
+a little hint about the post's content by adding the first paragraph of each of your
+posts:
+
+{% highlight html %}
+<ul>
+  {% raw %}{% for post in site.posts %}{% endraw %}
+    <li>
+      <a href="{% raw %}{{ post.url }}{% endraw %}">{% raw %}{{ post.title }}{% endraw %}</a>
+      <p>{% raw %}{{ post.excerpt }}{% endraw %}</p>
+    </li>
+  {% raw %}{% endfor %}{% endraw %}
+</ul>
+{% endhighlight %}
+
+If you don't like the automatically-generated post excerpt, it can be overridden by adding
+`excerpt` to your post's YAML front-matter.
+
 ## Highlighting code snippets
 
 Jekyll also has built-in support for syntax highlighting of code snippets using
-[Pygments](../extras), and including a code snippet in any post is easy. Just
-use the dedicated Liquid tag as follows:
+Pygments, and including a code snippet in any post is easy. Just use the
+dedicated Liquid tag as follows:
 
 {% highlight text %}
 {% raw %}{% highlight ruby %}{% endraw %}

data/site/docs/templates.md

@@ -37,6 +37,20 @@ common tasks easier.
         </p>
       </td>
     </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>Date to RFC-822 Format</strong></p>
+        <p>Convert a Date into the RFC-822 format used for RSS feeds.</p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{% raw %}{{ site.time | date_to_rfc822 }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class='output'>Mon, 17 Nov 2008 13:07:54 -0800</code>
+        </p>
+      </td>
+    </tr>
     <tr>
       <td>
         <p class='name'><strong>Date to String</strong></p>
@@ -93,6 +107,22 @@ common tasks easier.
         </p>
       </td>
     </tr>
+    <tr>
+      <td>
+        <p class='name'><strong>URI Escape</strong></p>
+        <p>
+          URI escape a string.
+        </p>
+      </td>
+      <td class='align-center'>
+        <p>
+         <code class='filter'>{% raw %}{{ “'foo, bar \\baz?'” | uri_escape }}{% endraw %}</code>
+        </p>
+        <p>
+          <code class='output'>foo,%20bar%20%5Cbaz?</code>
+        </p>
+      </td>
+    </tr>
     <tr>
       <td>
         <p class='name'><strong>Number of Words</strong></p>
@@ -166,9 +196,8 @@ root of your source directory. This will embed the contents of
 
 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).
+[Pygments](http://pygments.org/). When you run Jekyll, make sure you run it
+with `pygments` set to `true` in your configuration file.
 
 To render a code block with syntax highlighting, surround your code as follows:
 
@@ -234,3 +263,21 @@ You can also use this tag to create a link to a post in Markdown as follows:
 [Name of Link]({% post_url 2010-07-21-name-of-post %})
 {% endraw %}
 {% endhighlight %}
+
+### Gist
+
+Use the `gist` tag to easily embed a GitHub Gist onto your site:
+
+{% highlight text %}
+{% raw %}
+{% gist 5555251 %}
+{% endraw %}
+{% endhighlight %}
+
+You may also optionally specify the filename in the gist to display:
+
+{% highlight text %}
+{% raw %}
+{% gist 5555251 result.md %}
+{% endraw %}
+{% endhighlight %}

data/site/docs/upgrading.md

@@ -2,6 +2,7 @@
 layout: docs
 title: Upgrading
 prev_section: resources
+next_section: history
 permalink: /docs/upgrading/
 ---
 
@@ -25,24 +26,23 @@ and `jekyll serve` to do the same. And if you want Jekyll to automatically
 rebuild each time a file changes, just add the `--watch` flag at the end.
 
 <div class="note info">
-  <h5 markdown="1">Watching and Serving</h5>
+  <h5>Watching and Serving</h5>
   <p markdown="1">With the new subcommands, the way sites are previewed locally
    changed a bit. Instead of specifying `server: true` in the site's
    configuration file, use `jekyll serve`. The same hold's true for
-   `watch: true`. Instead, use the `--watch` flag with either `jekyll serve`
+   `watch: true`. Instead, use the `&#45;&#45;watch` flag with either `jekyll serve`
     or `jekyll build`.</p>
 </div>
 
 ### Absolute Permalinks
 
-In older Jekyll versions, one could use relative permalinks for pages in
-subdirectories. As of Jekyll v1.0, **we introduced absolute permalinks**,
-which do not take advantage of the page's directory position to write the
-permalink. As of Jekyll v1.0.2, a new switch, `relative_permalinks`,
-allows the user to turn relative permalinks on and off at will, in order
-to preserve the old behaviour, or use the new behaviour. As of v1.0.2,
-this switch defaults to `true`, but it will default to `false`
-in v1.1.0 and beyond.
+In Jekyll v1.0, we introduced absolute permalinks for pages in subdirectories.
+Until v1.1, it is **opt-in**. Starting with v1.1, however, absolute permalinks
+will become **opt-out**, meaning Jekyll will default to using absolute permalinks
+instead of relative permalinks.
+
+* To use absolute permalinks, set `relative_permalinks: false` in your configuration file.
+* To continue using relative permalinks, set `relative_permalinks: true` in your configuration file.
 
 <div class="note warning" id="absolute-permalinks-warning">
   <h5 markdown="1">Absolute permalinks will be default in v1.1 and on</h5>
@@ -53,6 +53,23 @@ in v1.1.0 and beyond.
   </p>
 </div>
 
+### Draft Posts
+
+Jekyll now lets you write draft posts, and allows you to easily preview how
+they will look prior to publishing. To start a draft, simply create a folder
+called `_drafts` in your site's source directory (e.g., alongside `_posts`),
+and add a new markdown file to it. To preview your new post, simply run the
+`jekyll serve` command with the `--drafts` flag.
+
+<div class="note info">
+  <h5 markdown="1">Drafts don't have dates</h5>
+  <p markdown="1">
+    Unlike posts, drafts don't have a date, since they haven't
+    been published yet. Rather than naming your draft something like
+    `2013-07-01-my-draft-post.md`, simply name the file what you'd like your
+    post to eventually be titled, here `my-draft-post.md`.</p>
+</div>
+
 ### Custom Config File
 
 Rather than passing individual flags via the command line, you can now pass an
@@ -74,31 +91,30 @@ to one or more config files (comma-delimited, no spaces).
 * `--paginate`
 
 <div class="note info">
-  <h5 markdown="1">The `--config` explicitly specifies your configuration file(s)</h5>
-  <p markdown="1">If you use the `--config` flag, Jekyll will ignore your
-    `config.yml` file. Want to merge a custom configuration with the normal
+  <h5>The config flag explicitly specifies your configuration file(s)</h5>
+  <p markdown="1">If you use the `&#45;&#45;config` flag, Jekyll will ignore your
+    `&#95;config.yml` file. Want to merge a custom configuration with the normal
     configuration? No problem. Jekyll will accept more than one custom config
     file via the command line. Config files cascade from right to left, such
-    that if I run `jekyll serve --config config.yml,config-dev.yml`,
-    the values in the config files on the right (`config-dev.yml`) overwrite
-    those on the left (`config.yml`) when both contain the same key.</p>
+    that if I run `jekyll serve &#45;&#45;config &#95;config.yml,&#95;config-dev.yml`,
+    the values in the config files on the right (`&#95;config-dev.yml`) overwrite
+    those on the left (`&#95;config.yml`) when both contain the same key.</p>
 </div>
 
-### Draft posts
+### New Config File Options
 
-Jekyll now lets you write draft posts, and allows you to easily preview how
-they will look prior to publishing. To start a draft, simply create a folder
-called `_drafts` in your site's source directory (e.g., alongside `_posts`),
-and add a new markdown file to it. To preview your new post, simply run the
-`Jekyll serve` command with the `--drafts` flag.
+Jekyll 1.0 introduced several new config file options. Before you upgrade, you
+should check to see if any of these are present in your pre-1.0 config file, and
+if so, make sure that you're using them properly:
 
-<div class="note info">
-  <h5 markdown="1">Drafts don't have dates</h5>
-  <p markdown="1">Unlike posts, drafts don't have a date, since they haven't
-  been published yet. Rather than naming your draft something like
-  `2013-07-01-my-draft-post.md`, simply name the file what you'd like your
-  post to eventually be titled, here `my-draft-post.md`.</p>
-</div>
+* `excerpt_separator`
+* `host`
+* `include`
+* `keep_files`
+* `layouts`
+* `show_drafts`
+* `timezone`
+* `url`
 
 ### Baseurl