jekyll-docs 2.5.3 → 3.0.3

data/site/_docs/index.md

@@ -0,0 +1,56 @@
+---
+layout: docs
+title: Welcome
+permalink: /docs/home/
+---
+
+This site aims to be a comprehensive guide to Jekyll. We’ll cover topics such
+as getting your site up and running, creating and managing your content,
+customizing the way your site works and looks, deploying to various
+environments, and give you 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
+a converter (like [Markdown](http://daringfireball.net/projects/markdown/))
+and our [Liquid](https://github.com/Shopify/liquid/wiki) renderer, 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**.
+
+## Helpful Hints
+
+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>
+
+<div class="note unreleased">
+  <h5>You'll see this by a feature that hasn't been released</h5>
+  <p>Some pieces of this website are for future versions of Jekyll that
+    are not yet released.</p>
+</div>
+
+If you come across anything along the way that we haven’t covered, or if you
+know of a tip you think others would find handy, please [file an
+issue]({{ site.repository }}/issues/new) and we’ll see about
+including it in this guide.

data/site/_docs/installation.md

@@ -0,0 +1,106 @@
+---
+layout: docs
+title: Installation
+permalink: /docs/installation/
+---
+
+Getting Jekyll installed and ready-to-go should only take a few minutes. If it
+ever becomes a pain in the ass, please [file an
+issue]({{ site.repository }}/issues/new) (or submit a pull request)
+describing the issue you encountered and how we might make the process easier.
+
+### Requirements
+
+Installing Jekyll is easy and straight-forward, but there are a few
+requirements you’ll need to make sure your system has before you start.
+
+- [Ruby](http://www.ruby-lang.org/en/downloads/) (including development
+  headers, v1.9.3 or above for Jekyll 2 and v2 or above for Jekyll 3)
+- [RubyGems](http://rubygems.org/pages/download)
+- Linux, Unix, or Mac OS X
+- [NodeJS](http://nodejs.org), or another JavaScript runtime (Jekyll 2 and
+earlier, for CoffeeScript support).
+- [Python 2.7](https://www.python.org/downloads/) (for Jekyll 2 and earlier)
+
+<div class="note info">
+  <h5>Running Jekyll on Windows</h5>
+  <p>
+    While Windows is not officially supported, it is possible to get it running
+    on Windows. Special instructions can be found on our
+    <a href="../windows/#installation">Windows-specific docs page</a>.
+  </p>
+</div>
+
+## Install with RubyGems
+
+The best way to install Jekyll is via
+[RubyGems](http://rubygems.org/pages/download). At the terminal prompt,
+simply run the following command to install Jekyll:
+
+{% highlight bash %}
+$ gem install jekyll
+{% endhighlight %}
+
+All of Jekyll’s gem dependencies 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]({{ site.repository }}/issues/new) so the Jekyll
+community can improve the experience for everyone.
+
+<div class="note info">
+  <h5>Installing Xcode Command-Line Tools</h5>
+  <p>
+    If you run into issues installing Jekyll's dependencies which make use of
+    native extensions and are using Mac OS X, you will need to install Xcode
+    and the Command-Line Tools it ships with. Download in
+    <code>Preferences &#8594; Downloads &#8594; Components</code>.
+  </p>
+</div>
+
+## Pre-releases
+
+In order to install a pre-release, make sure you have all the requirements
+installed properly and run:
+
+{% highlight bash %}
+gem install jekyll --pre
+{% endhighlight %}
+
+This will install the latest pre-release. If you want a particular pre-release,
+use the `-v` switch to indicate the version you'd like to install:
+
+{% highlight bash %}
+gem install jekyll -v '2.0.0.alpha.1'
+{% endhighlight %}
+
+If you'd like to install a development version of Jekyll, the process is a bit
+more involved. This gives you the advantage of having the latest and greatest,
+but may be unstable.
+
+{% highlight bash %}
+$ git clone git://github.com/jekyll/jekyll.git
+$ cd jekyll
+$ script/bootstrap
+$ bundle exec rake build
+$ ls pkg/*.gem | head -n 1 | xargs gem install -l
+{% endhighlight %}
+
+## 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 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
+    want to enable syntax highlighting using <a href="http://pygments.org/">Pygments</a>
+    or <a href="https://github.com/jayferd/rouge">Rouge</a>. You should really
+    <a href="../templates/#code-snippet-highlighting">check out how to
+    do that</a> before you go any farther.
+  </p>
+</div>
+
+Now that you’ve got everything installed, let’s get to work!

data/site/_docs/migrations.md

@@ -0,0 +1,9 @@
+---
+layout: docs
+title: Blog migrations
+permalink: /docs/migrations/
+---
+
+If you’re switching to Jekyll from another blogging system, Jekyll’s importers
+can help you with the move. To learn more about importing your site to Jekyll,
+visit our [`jekyll-import` docs site](http://import.jekyllrb.com/docs/home/).

data/site/_docs/pages.md

@@ -0,0 +1,84 @@
+---
+layout: docs
+title: Creating pages
+permalink: /docs/pages/
+---
+
+In addition to [writing posts](../posts/), another thing you may want to do
+with your Jekyll site is create static pages. By taking advantage of the way
+Jekyll copies files and directories, this is easy to do.
+
+## Homepage
+
+Just about every web server configuration you come across will look for an HTML
+file called `index.html` (by convention) in the site's 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 use layouts and/or includes, even the
+    homepage. Common content, like headers and footers, make excellent
+    candidates for extraction into a layout.
+  </p>
+</div>
+
+## Where additional pages live
+
+Where you put HTML files for pages depends on how you want the pages to work.
+There are two main ways of creating pages:
+
+- Place named HTML files for each page in your site's root folder.
+- Create a folder in the site's root for each page, and place an index.html
+file in each page folder.
+
+Both methods work fine (and can be used in conjunction with each other),
+with the only real difference being the resulting URLs.
+
+### Named HTML files
+
+The simplest way of adding a page is just to add an 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://example.com/about.html
+|-- index.html    # => http://example.com/
+└── contact.html  # => http://example.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. Here's an example of what this structure
+might look like:
+
+{% highlight bash %}
+.
+├── _config.yml
+├── _includes/
+├── _layouts/
+├── _posts/
+├── _site/
+├── about/
+|   └── index.html  # => http://example.com/about/
+├── contact/
+|   └── index.html  # => http://example.com/contact/
+└── index.html      # => http://example.com/
+{% endhighlight %}
+
+This approach may not suit everyone, but for people who like clean URLs it’s
+simple and it works. In the end the decision is yours!

data/site/_docs/pagination.md

@@ -0,0 +1,221 @@
+---
+layout: docs
+title: Pagination
+permalink: /docs/pagination/
+---
+
+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 listings.
+
+<div class="note info">
+  <h5>Pagination only works within HTML files</h5>
+  <p>
+    Pagination does not work from within Markdown or Textile files from
+    your Jekyll site. Pagination works when called from within the HTML
+    file, named <code>index.html</code>, which optionally may reside in and
+    produce pagination from within a subdirectory, via the
+    <code>paginate_path</code> configuration value.
+  </p>
+</div>
+
+## Enable pagination
+
+To enable pagination for your blog, add a line to the `_config.yml` file that
+specifies how many items should be displayed per page:
+
+{% 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.
+
+You may also specify the destination of the pagination pages:
+
+{% highlight yaml %}
+paginate_path: "/blog/page:num/"
+{% endhighlight %}
+
+This will read in `blog/index.html`, send it each pagination page in Liquid as
+`paginator` and write the output to `blog/page:num/`, where `:num` is the
+pagination page number, starting with `2`. If a site has 12 posts and specifies
+`paginate: 5`, Jekyll will write `blog/index.html` with the first 5 posts, `blog/page2/index.html` with the next 5 posts
+and `blog/page3/index.html` with the last 2 posts into the destination
+directory.
+
+<div class="note warning">
+  <h5>Don't set a permalink</h5>
+  <p>
+    Setting a permalink in the front matter of your blog page will cause
+    pagination to break. Just omit the permalink.
+  </p>
+</div>
+
+## Liquid Attributes Available
+
+The pagination plugin exposes the `paginator` liquid object with the following
+attributes:
+
+<div class="mobile-side-scroller">
+<table>
+  <thead>
+    <tr>
+      <th>Attribute</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><p><code>page</code></p></td>
+      <td><p>current page number</p></td>
+    </tr>
+    <tr>
+      <td><p><code>per_page</code></p></td>
+      <td><p>number of posts per page</p></td>
+    </tr>
+    <tr>
+      <td><p><code>posts</code></p></td>
+      <td><p>a list of posts for the current page</p></td>
+    </tr>
+    <tr>
+      <td><p><code>total_posts</code></p></td>
+      <td><p>total number of posts in the site</p></td>
+    </tr>
+    <tr>
+      <td><p><code>total_pages</code></p></td>
+      <td><p>number of pagination pages</p></td>
+    </tr>
+    <tr>
+      <td><p><code>previous_page</code></p></td>
+      <td>
+          <p>
+              page number of the previous pagination page,
+              or <code>nil</code> if no previous page exists
+          </p>
+      </td>
+    </tr>
+    <tr>
+      <td><p><code>previous_page_path</code></p></td>
+      <td>
+          <p>
+              path of previous pagination page,
+              or <code>nil</code> if no previous page exists
+          </p>
+      </td>
+    </tr>
+    <tr>
+      <td><p><code>next_page</code></p></td>
+      <td>
+          <p>
+              page number of the next pagination page,
+              or <code>nil</code> if no subsequent page exists
+          </p>
+      </td>
+    </tr>
+    <tr>
+      <td><p><code>next_page_path</code></p></td>
+      <td>
+          <p>
+              path of next pagination page,
+              or <code>nil</code> if no subsequent page exists
+          </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+</div>
+
+<div class="note info">
+  <h5>Pagination does not support tags or categories</h5>
+  <p>Pagination pages through every post in the <code>posts</code>
+  variable regardless of variables defined in the YAML Front Matter of
+  each. It does not currently allow paging over groups of posts linked
+  by a common tag or category. It cannot include any collection of
+  documents because it is restricted to posts.</p>
+</div>
+
+## 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 %}
+{% raw %}
+---
+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="{{ paginator.previous_page_path }}" 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="{{ paginator.next_page_path }}" class="next">Next</a>
+  {% else %}
+    <span class="next ">Next</span>
+  {% endif %}
+</div>
+{% endraw %}
+{% 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 %}
+{% raw %}
+{% if paginator.total_pages > 1 %}
+<div class="pagination">
+  {% if paginator.previous_page %}
+    <a href="{{ paginator.previous_page_path | prepend: site.baseurl | replace: '//', '/' }}">&laquo; Prev</a>
+  {% else %}
+    <span>&laquo; Prev</span>
+  {% endif %}
+
+  {% for page in (1..paginator.total_pages) %}
+    {% if page == paginator.page %}
+      <em>{{ page }}</em>
+    {% elsif page == 1 %}
+      <a href="{{ paginator.previous_page_path | prepend: site.baseurl | replace: '//', '/' }}">{{ page }}</a>
+    {% else %}
+      <a href="{{ site.paginate_path | prepend: site.baseurl | replace: '//', '/' | replace: ':num', page }}">{{ page }}</a>
+    {% endif %}
+  {% endfor %}
+
+  {% if paginator.next_page %}
+    <a href="{{ paginator.next_page_path | prepend: site.baseurl | replace: '//', '/' }}">Next &raquo;</a>
+  {% else %}
+    <span>Next &raquo;</span>
+  {% endif %}
+</div>
+{% endif %}
+{% endraw %}
+{% endhighlight %}