jekyll 0.12.1 → 1.0.0.beta1

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

@@ -0,0 +1,180 @@
+---
+layout: docs
+title: Blog migrations
+prev_section: variables
+next_section: templates
+---
+
+If you’re switching to Jekyll from another blogging system, Jekyll’s migrators can help you with the move. Most methods listed on this page require read access to the database to generate posts from your old system. Each method generates `.markdown` posts in the `_posts` directory based on the entries in the database.
+
+## Preparing for migrations
+
+The migrators are [built-in to the Jekyll gem](https://github.com/mojombo/jekyll/tree/master/lib/jekyll/migrators), and require a few things to be set up in your project directory before they are run. This should all be done from the root folder of your Jekyll project.
+
+{% highlight bash %}
+$ mkdir _import
+$ gem install sequel mysqlplus
+{% endhighlight %}
+
+You should now be all set to run the migrators below.
+
+<div class="note info">
+  <h5>Note: Always double-check migrated content</h5>
+  <p>Import scripts may not distinguish between published or private posts, so you should always check that the content Jekyll generates for you appears as you intended.</p>
+</div>
+
+## WordPress
+
+### Wordpress export files
+
+If hpricot is not already installed, you will need to run `gem install hpricot`. Next, export your blog using the Wordpress export utility. Assuming that 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")'
+{% 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>
+</div>
+
+### Using Wordpress MySQL server connection
+
+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")'
+{% endhighlight %}
+
+If you are using Webfaction and have to set an [SSH tunnel](http://docs.webfaction.com/user-guide/databases.html?highlight=mysql#starting-an-ssh-tunnel-with-ssh), make sure to make the hostname (`127.0.0.1`) explicit, otherwise MySQL may block 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")'
+{% endhighlight %}
+
+### Further Wordpress migration alternatives
+
+While the above methods work, they do not import much of the metadata that is usually stored in Wordpress posts and pages. If you need to export things like pages, tags, custom fields, image attachments and so on, the following resources might be useful to you:
+
+- [Exitwp](https://github.com/thomasf/exitwp) is a configurable tool written in Python for migrating one or more Wordpress blogs into Jekyll (Markdown) format while keeping as much metadata as possible. Exitwp also downloads attachments and pages.
+- [A great article](http://vitobotta.com/how-to-migrate-from-wordpress-to-jekyll/) with a step-by-step guide for migrating a Wordpress blog to Jekyll while keeping most of the structure and metadata.
+- [wpXml2Jekyll](https://github.com/theaob/wpXml2Jekyll) is an executable windows application for creating Markdown posts from your Wordpress XML file.
+
+## Drupal
+
+If you’re migrating from [Drupal](), there is [a migrator](https://github.com/mojombo/jekyll/blob/master/lib/jekyll/migrators/drupal.rb) for you too:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/drupal";
+    Jekyll::Drupal.process("database", "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 on future versions of Drupal. Please update it and send us a pull request if necessary.</p>
+</div>
+
+## Movable Type
+
+To import posts from Movable Type:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/mt";
+    Jekyll::MT.process("database", "user", "pass")'
+{% endhighlight %}
+
+## Typo
+
+To import posts from Typo:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/typo";
+    Jekyll::Typo.process("database", "user", "pass")'
+{% endhighlight %}
+
+This code also has only been tested with Typo version 4+.
+
+## TextPattern
+
+To import posts from TextPattern:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/textpattern";
+    Jekyll::TextPattern.process("database_name", "username", "password", "hostname")'
+{% endhighlight %}
+
+You will need to run the above from the parent directory of your `_import` folder. For example, if `_import` is located in `/path/source/_import`, you will need to run this code from `/path/source`. The hostname defaults to `localhost`, all other variables are required. You may need to adjust the code used to filter entries. Left alone, it will attempt to pull all entries that are live or sticky.
+
+## Mephisto
+
+To import posts from Mephisto:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/mephisto";
+    Jekyll::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"})'
+{% endhighlight %}
+
+## Blogger (Blogspot)
+
+To import posts from Blogger, see [this post about migrating from Blogger to Jekyll](http://coolaj86.info/articles/migrate-from-blogger-to-jekyll.html). If that doesn’t work for you, you might want to try some of the following alternatives:
+
+- [@kennym](https://github.com/kennym) created a [little migration script](https://gist.github.com/1115810), because the solutions in the previous article didn't work out for him.
+- [@ngauthier](https://github.com/ngauthier) created [another importer](https://gist.github.com/1506614) that imports comments, and does so via blogger’s archive instead of the RSS feed.
+- [@juniorz](https://github.com/juniorz) created [yet another importer](https://gist.github.com/1564581) that works for [Octopress](http://octopress.org). It is like [@ngauthier’s version](https://gist.github.com/1506614) but separates drafts from posts, as well as importing tags and permalinks.
+
+## Posterous
+
+To import posts from your primary Posterous blog:
+
+{% highlight bash %}
+$ ruby -rubygems -e 'require "jekyll/migrators/posterous";
+    Jekyll::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")'
+{% endhighlight %}
+
+There is also an [alternative Posterous migrator](https://github.com/pepijndevos/jekyll/blob/patch-1/lib/jekyll/migrators/posterous.rb) that maintains permalinks and attempts to import images too.
+
+## Tumblr
+
+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")'
+{% endhighlight %}
+
+## Other Systems
+
+If you have a system that there isn’t currently a migrator for, you should consider writing one and sending us a pull request.

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

@@ -0,0 +1,62 @@
+---
+layout: docs
+title: Creating pages
+prev_section: posts
+next_section: variables
+---
+
+As well as [writing posts](../posts), the other thing you may want to do with your Jekyll site is create static pages. This is pretty simple to do, simply by taking advantage of the way Jekyll copies files and directories.
+
+## Homepage
+
+Just about every web server configuration you’ll come across will look for a HTML file called `index.html` (by convention) in the site root folder and display that as the homepage. Unless the web server you’re using is configured to look for some different filename as the default, this file will turn into the homepage of your Jekyll-generated site.
+
+<div class="note">
+  <h5>ProTip™: Use layouts on your homepage</h5>
+  <p>Any HTML file on your site can make use of layouts and includes, even the homepage. It’s usually a good idea to extract everything that is the same across all your pages into an included file in a layout.</p>
+</div>
+
+## Where additional pages live
+
+Where you put HTML files for pages depends on how you want the pages to work, since there are two main ways of creating pages:
+
+- By placing named HTML files for each page in the site root folder.
+- Create a folder in the site root for each page, and placing an index.html file in each page folder.
+
+Both methods work fine (and can be used in conduction with each other), with the only real difference being the resulting URLs each page has.
+
+### Named HTML files
+
+The simplest way of adding a page is just to add a HTML file in the root directory with a suitable name for the page you want to create. For a site with a homepage, an about page, and a contact page, here’s what the root directory and associated URLs might look like.
+
+{% highlight bash %}
+.
+|-- _config.yml
+|-- _includes
+|-- _layouts
+|-- _posts
+|-- _site
+|-- about.html    #=> http://yoursite.com/about.html
+|-- index.html    #=> http://yoursite.com/
+└── contact.html  #=> http://yoursite.com/contact.html
+{% endhighlight %}
+
+### Named folders containing index HTML files
+
+There is nothing wrong with the above method, however some people like to keep their URLs free from things like filename extensions. To achieve clean URLs for pages using Jekyll, you simply need to create a folder for each top-level page you want, and then place an `index.html` file in each page’s folder. This way the page URL ends up being the folder name, and the web server will serve up the respective `index.html` file. An example of what this structure would look like is as follows:
+
+{% highlight bash %}
+.
+├── _config.yml
+├── _includes
+├── _layouts
+├── _posts
+├── _site
+├── about
+|   └── index.html  #=> http://yoursite.com/about/
+├── contact
+|   └── index.html  #=> http://yoursite.com/contact/
+└── index.html      #=> http://yoursite.com/
+{% endhighlight %}
+
+This approach may not suit everyone, but for people who like clear URLs it’s simple and it works. In the end the decision is yours!

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

@@ -0,0 +1,116 @@
+---
+layout: docs
+title: Pagination
+prev_section: permalinks
+next_section: plugins
+---
+
+With many websites—especially blogs—it’s very common to break the main listing of posts up into smaller lists and display them over multiple pages. Jekyll has pagination built-in, so you can automatically generate the appropriate files and folders you need for paginated post listings.
+
+<div class="note info">
+  <h5>Pagination only works within HTML files</h5>
+  <p>Pagination does not work with Markdown or Textile files in your Jekyll site. It will only work when used within HTML files. Since you’ll likely be using this for the list of posts, this probably won’t be an issue.</p>
+</div>
+
+## Enable pagination
+
+The first thing you need to do to enable pagination for your blog is add a line to the `_config.yml` Jekyll configuration file that specifies how many items should be displayed per page. Here is what the line should look like:
+
+{% highlight yaml %}
+paginate: 5
+{% endhighlight %}
+
+The number should be the maximum number of posts you’d like to be displayed per-page in the generated site.
+
+## Render the paginated posts
+
+The next thing you need to do is to actually display your posts in a list using the `paginator` variable that will now be available to you. You’ll probably want to do this in one of the main pages of your site. Here’s one example of a simple way of rendering paginated posts in a HTML file:
+
+{% highlight html %}
+---
+layout: default
+title: My Blog
+---
+
+<!-- This loops through the paginated posts -->
+{{ "{% for post in paginator.posts " }}%}
+  <h1><a href="{{ "{{ post.url " }}}}">{{ "{{ post.title " }}}}</a></h1>
+  <p class="author">
+    <span class="date">{{ "{{post.date" }}}}</span>
+  </p>
+  <div class="content">
+    {{ "{{ post.content " }}}}
+  </div>
+{{ "{% endfor " }}%}
+
+<!-- Pagination links -->
+<div class="pagination">
+  {{ "{% if paginator.previous_page " }}%}
+    <a href="/page{{ "{{paginator.previous_page" }}}}" class="previous">Previous</a>
+  {{ "{% else " }}%}
+    <span class="previous">Previous</span>
+  {{ "{% endif " }}%}
+  <span class="page_number ">Page: {{ "{{paginator.page" }}}} of {{ "{{paginator.total_pages" }}}}</span>
+  {{ "{% if paginator.next_page " }}%}
+    <a href="/page{{ "{{paginator.next_page" }}}}" class="next ">Next</a>
+  {{ "{% else " }}%}
+    <span class="next ">Next</span>
+  {{ "{% endif " }}%}
+</div>
+{% endhighlight %}
+
+<div class="note warning">
+  <h5>Beware the page one edge-case</h5>
+  <p>Jekyll does not generate a ‘page1’ folder, so the above code will not work when a <code>/page1</code> link is produced. See below for a way to handle this if it’s a problem for you.</p>
+</div>
+
+The following HTML snippet should handle page one, and render a list of each page with links to all but the current page.
+
+{% highlight html %}
+<div id="post-pagination" class="pagination">
+  {{ "{% if paginator.previous_page " }}%}
+    <p class="previous">
+      {{ "{% if paginator.previous_page == 1 " }}%}
+        <a href="/">Previous</a>
+      {{ "{% else " }}%}
+        <a href="/page{{ "{{paginator.previous_page" }}}}">Previous</a>
+      {{ "{% endif " }}%}
+    </p>
+  {{ "{% else " }}%}
+    <p class="previous disabled">
+      <span>Previous</span>
+    </p>
+  {{ "{% endif " }}%}
+
+  <ul class="pages">
+    <li class="page">
+      {{ "{% if paginator.page == 1 " }}%}
+        <span class="current-page">1</span>
+      {{ "{% else " }}%}
+        <a href="/">1</a>
+      {{ "{% endif " }}%}
+    </li>
+
+    {{ "{% for count in (2..paginator.total_pages) " }}%}
+      <li class="page">
+        {{ "{% if count == paginator.page " }}%}
+          <span class="current-page">{{ "{{count" }}}}</span>
+        {{ "{% else " }}%}
+          <a href="/page{{ "{{count" }}}}">{{ "{{count" }}}}</a>
+        {{ "{% endif " }}%}
+      </li>
+    {{ "{% endfor " }}%}
+  </ul>
+
+  {{ "{% if paginator.next_page " }}%}
+    <p class="next">
+      <a href="/page{{ "{{paginator.next_page" }}}}">Next</a>
+    </p>
+  {{ "{% else " }}%}
+    <p class="next disabled">
+      <span>Next</span>
+    </p>
+  {{ "{% endif " }}%}
+
+</div>
+{% endhighlight %}

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

@@ -0,0 +1,163 @@
+---
+layout: docs
+title: Permalinks
+prev_section: templates
+next_section: pagination
+---
+
+Jekyll supports a flexible way to build your site’s URLs. You can
+specify the permalinks for your site through the [Configuration](../configuration) or on the [YAML Front Matter](../frontmatter) for each post. You’re free to choose one of the built-in styles to create your links or craft your own. The default style is always `date`.
+
+## Template variables
+
+<table>
+  <thead>
+    <tr>
+      <th>Variable</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p><code>year</code></p>
+      </td>
+      <td>
+        <p>Year from the post’s filename</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>month</code></p>
+      </td>
+      <td>
+        <p>Month from the post’s filename</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>day</code></p>
+      </td>
+      <td>
+        <p>Day from the post’s filename</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>title</code></p>
+      </td>
+      <td>
+        <p>Title from the post’s filename</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>categories</code></p>
+      </td>
+      <td>
+        <p>The specified categories for this post. Jekyll automatically parses out double slashes in the URLs, so if no categories are present, it basically ignores this.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>i_month</code></p>
+      </td>
+      <td>
+        <p> Month from the post’s filename without leading zeros.</p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>i_day</code></p>
+      </td>
+      <td>
+        <p>Day from the post’s filename without leading zeros.</p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+## Built-in permalink styles
+
+<table>
+  <thead>
+    <tr>
+      <th>Permalink Style</th>
+      <th>URL Template</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p><code>date</code></p>
+      </td>
+      <td>
+        <p><code>/:categories/:year/:month/:day/:title.html</code></p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>pretty</code></p>
+      </td>
+      <td>
+        <p><code>/:categories/:year/:month/:day/:title/</code></p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>none</code></p>
+      </td>
+      <td>
+        <p><code>/:categories/:title.html</code></p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+## Permalink style examples
+
+Given a post named: `/2009-04-29-slap-chop.textile`
+
+<table>
+  <thead>
+    <tr>
+      <th>Permalink Setting</th>
+      <th>Resulting Permalink URL</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <p>None specified, or <code>permalink: date</code></p>
+      </td>
+      <td>
+        <p><code>/2009/04/29/slap-chop.html</code></p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>permalink: pretty</code></p>
+      </td>
+      <td>
+        <p><code>/2009/04/29/slap-chop/index.html</code></p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>permalink: /:month-:day-:year/:title.html</code></p>
+      </td>
+      <td>
+        <p><code>/04-29-2009/slap-chop.html</code></p>
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <p><code>permalink: /blog/:year/:month/:day/:title</code></p>
+      </td>
+      <td>
+        <p><code>/blog/2009/04/29/slap-chop/index.html</code></p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+