jekyll-docs 3.0.3 → 3.1.2

data/site/_docs/upgrading.md

@@ -4,137 +4,7 @@ title: Upgrading
 permalink: /docs/upgrading/
 ---
 
-Upgrading from an older version of Jekyll? A few things have changed in 1.0
-that you'll want to know about.
+Upgrading from an older version of Jekyll? Upgrading to a new major version of Jekyll (e.g. from v2.x to v3.x) may cause some headaches. Take the following guides to aid your upgrade:
 
-Before we dive in, go ahead and fetch the latest version of Jekyll:
-
-{% highlight bash %}
-$ gem update jekyll
-{% endhighlight %}
-
-<div class="note feature">
-  <h5 markdown="1">Diving in</h5>
-  <p markdown="1">Want to get a new Jekyll site up and running quickly? Simply
-   run <code>jekyll new SITENAME</code> to create a new folder with a bare bones
-   Jekyll site.</p>
-</div>
-
-### The Jekyll Command
-
-For better clarity, Jekyll now accepts the commands `build` and `serve`.
-Whereas before you might simply run the command `jekyll` to generate a site
-and `jekyll --server` to view it locally, in v2.0 (and later) you should
-use the subcommands `jekyll build` and `jekyll serve` to build and preview
-your site.
-
-<div class="note info">
-  <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 holds true for
-   `watch: true`. Instead, use the `--watch` flag with either `jekyll serve`
-    or `jekyll build`.</p>
-</div>
-
-### Absolute Permalinks
-
-In Jekyll v1.0, we introduced absolute permalinks for pages in
-subdirectories. Starting with v2.0, absolute permalinks are opt-out,
-meaning Jekyll will default to using absolute permalinks instead of
-relative permalinks. Relative permalink backwards-compatibility was removed in v3.0.
-
-<div class="note warning" id="absolute-permalinks-warning">
-  <h5 markdown="1">Absolute permalinks will be required in v3.0 and on</h5>
-  <p markdown="1">
-    Starting with Jekyll v3.0, relative permalinks functionality will be removed and thus unavailable for use.
-  </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 entire custom Jekyll config file. This helps to distinguish between
-environments, or lets you programmatically override user-specified
-defaults. Simply add the `--config` flag to the `jekyll` command, followed
-by the path to one or more config files (comma-delimited, no spaces).
-
-#### As a result, the following command line flags are now deprecated:
-
-* `--no-server`
-* `--no-auto` (now `--no-watch`)
-* `--auto` (now `--watch`)
-* `--server`
-* `--url=`
-* `--maruku`, `--rdiscount`, and `--redcarpet`
-* `--pygments`
-* `--permalink=`
-* `--paginate`
-
-<div class="note info">
-  <h5>The config flag 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
-    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>
-</div>
-
-### New Config File Options
-
-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:
-
-* `excerpt_separator`
-* `host`
-* `include`
-* `keep_files`
-* `layouts`
-* `show_drafts`
-* `timezone`
-* `url`
-
-### Baseurl
-
-Often, you'll want the ability to run a Jekyll site in multiple places,
-such as previewing locally before pushing to GitHub Pages. Jekyll 1.0 makes
-that easier with the new `--baseurl` flag. To take advantage of this
-feature, first add the production `baseurl` to your site's `_config.yml`
-file. Then, throughout the site, simply prefix relative URLs
-with `{% raw %}{{ site.baseurl }}{% endraw %}`.
-When you're ready to preview your site locally, pass along the `--baseurl`
-flag with your local baseurl (most likely `/`) to `jekyll serve` and Jekyll
-will swap in whatever you've passed along, ensuring all your links work as
-you'd expect in both environments.
-
-
-<div class="note warning">
-  <h5 markdown="1">All page and post URLs contain leading slashes</h5>
-  <p markdown="1">If you use the method described above, please remember
-  that the URLs for all posts and pages contain a leading slash. Therefore,
-  concatenating the site baseurl and the post/page url where
-  `site.baseurl = /` and `post.url = /2013/06/05/my-fun-post/` will
-  result in two leading slashes, which will break links. It is thus
-  suggested that prefixing with `site.baseurl` only be used when the
-  `baseurl` is something other than the default of `/`.</p>
-</div>
+- [From 0.x to 1.x and 2.x](/docs/upgrading/0-to-2/)
+- [From 2.x to 3.x](/docs/upgrading/2-to-3/)

data/site/_docs/upgrading/0-to-2.md

@@ -0,0 +1,140 @@
+---
+layout: docs
+title: Upgrading from 0.x to 2.x
+permalink: /docs/upgrading/0-to-2/
+---
+
+Upgrading from an older version of Jekyll? A few things have changed in 1.0
+and 2.0 that you'll want to know about.
+
+Before we dive in, go ahead and fetch the latest version of Jekyll:
+
+{% highlight bash %}
+$ gem update jekyll
+{% endhighlight %}
+
+<div class="note feature">
+  <h5 markdown="1">Diving in</h5>
+  <p markdown="1">Want to get a new Jekyll site up and running quickly? Simply
+   run <code>jekyll new SITENAME</code> to create a new folder with a bare bones
+   Jekyll site.</p>
+</div>
+
+### The Jekyll Command
+
+For better clarity, Jekyll now accepts the commands `build` and `serve`.
+Whereas before you might simply run the command `jekyll` to generate a site
+and `jekyll --server` to view it locally, in v2.0 (and later) you should
+use the subcommands `jekyll build` and `jekyll serve` to build and preview
+your site.
+
+<div class="note info">
+  <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 holds true for
+   `watch: true`. Instead, use the `--watch` flag with either `jekyll serve`
+    or `jekyll build`.</p>
+</div>
+
+### Absolute Permalinks
+
+In Jekyll v1.0, we introduced absolute permalinks for pages in
+subdirectories. Starting with v2.0, absolute permalinks are opt-out,
+meaning Jekyll will default to using absolute permalinks instead of
+relative permalinks. Relative permalink backwards-compatibility was removed in v3.0.
+
+<div class="note warning" id="absolute-permalinks-warning">
+  <h5 markdown="1">Absolute permalinks will be required in v3.0 and on</h5>
+  <p markdown="1">
+    Starting with Jekyll v3.0, relative permalinks functionality will be removed and thus unavailable for use.
+  </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 entire custom Jekyll config file. This helps to distinguish between
+environments, or lets you programmatically override user-specified
+defaults. Simply add the `--config` flag to the `jekyll` command, followed
+by the path to one or more config files (comma-delimited, no spaces).
+
+#### As a result, the following command line flags are now deprecated:
+
+* `--no-server`
+* `--no-auto` (now `--no-watch`)
+* `--auto` (now `--watch`)
+* `--server`
+* `--url=`
+* `--maruku`, `--rdiscount`, and `--redcarpet`
+* `--pygments`
+* `--permalink=`
+* `--paginate`
+
+<div class="note info">
+  <h5>The config flag 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
+    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>
+</div>
+
+### New Config File Options
+
+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:
+
+* `excerpt_separator`
+* `host`
+* `include`
+* `keep_files`
+* `layouts`
+* `show_drafts`
+* `timezone`
+* `url`
+
+### Baseurl
+
+Often, you'll want the ability to run a Jekyll site in multiple places,
+such as previewing locally before pushing to GitHub Pages. Jekyll 1.0 makes
+that easier with the new `--baseurl` flag. To take advantage of this
+feature, first add the production `baseurl` to your site's `_config.yml`
+file. Then, throughout the site, simply prefix relative URLs
+with `{% raw %}{{ site.baseurl }}{% endraw %}`.
+When you're ready to preview your site locally, pass along the `--baseurl`
+flag with your local baseurl (most likely `/`) to `jekyll serve` and Jekyll
+will swap in whatever you've passed along, ensuring all your links work as
+you'd expect in both environments.
+
+
+<div class="note warning">
+  <h5 markdown="1">All page and post URLs contain leading slashes</h5>
+  <p markdown="1">If you use the method described above, please remember
+  that the URLs for all posts and pages contain a leading slash. Therefore,
+  concatenating the site baseurl and the post/page url where
+  `site.baseurl = /` and `post.url = /2013/06/05/my-fun-post/` will
+  result in two leading slashes, which will break links. It is thus
+  suggested that prefixing with `site.baseurl` only be used when the
+  `baseurl` is something other than the default of `/`.</p>
+</div>

data/site/_docs/upgrading/2-to-3.md

@@ -0,0 +1,126 @@
+---
+layout: docs
+title: Upgrading from 2.x to 3.x
+permalink: /docs/upgrading/2-to-3/
+---
+
+Upgrading from an older version of Jekyll? A few things have changed in 3.0
+that you'll want to know about.
+
+Before we dive in, go ahead and fetch the latest version of Jekyll:
+
+{% highlight bash %}
+$ gem update jekyll
+{% endhighlight %}
+
+Please note: Jekyll 3 requires Ruby version >= 2.0.0.
+
+<div class="note feature">
+  <h5 markdown="1">Diving in</h5>
+  <p markdown="1">Want to get a new Jekyll site up and running quickly? Simply
+   run <code>jekyll new SITENAME</code> to create a new folder with a bare bones
+   Jekyll site.</p>
+</div>
+
+### site.collections has changed
+
+In 2.x, your iterations over `site.collections` yielded an array with the collection
+label and the collection object as the first and second items, respectively. In 3.x,
+this complication has been removed and iterations now yield simply the collection object.
+A simple conversion must be made in your templates:
+
+- `collection[0]` becomes `collection.label`
+- `collection[1]` becomes `collection`
+
+When iterating over `site.collections`, ensure the above conversions are made.
+
+For `site.collections.myCollection` in Jekyll 2, you now do:
+
+{% highlight liquid %}
+{% raw %}
+{% assign myCollection = site.collections | where: "label", "myCollection" | first %}
+{% endraw %}
+{% endhighlight %}
+
+This is a bit cumbersome at first, but is easier than a big `for` loop.
+
+### Dropped dependencies
+
+We dropped a number of dependencies the Core Team felt were optional. As such, in 3.0, they must be explicitly installed and included if you use any of the features. They are:
+
+- jekyll-paginate – Jekyll's pagination solution from days past
+- jekyll-coffeescript – processing of CoffeeScript
+- jekyll-gist – the `gist` Liquid tag
+- pygments.rb – the Pygments highlighter
+- redcarpet – the Markdown processor
+- toml – an alternative to YAML for configuration files
+- classifier-reborn – for `site.related_posts`
+
+### Future posts
+
+A seeming feature regression in 2.x, the `--future` flag was automatically _enabled_.
+The future flag allows post authors to give the post a date in the future and to have
+it excluded from the build until the system time is equal or after the post time.
+In Jekyll 3, this has been corrected. **Now, `--future` is disabled by default.**
+This means you will need to include `--future` if you want your future-dated posts to
+generate when running `jekyll build` or `jekyll serve`.
+
+### Layout metadata
+
+Introducing: `layout`. In Jekyll 2 and below, any metadata in the layout was merged onto
+the `page` variable in Liquid. This caused a lot of confusion in the way the data was
+merged and some unexpected behaviour. In Jekyll 3, all layout data is accessible via `layout`
+in Liquid. For example, if your layout has `class: my-layout` in its YAML front matter,
+then the layout can access that via `{% raw %}{{ layout.class }}{% endraw %}`.
+
+### Syntax highlighter changed
+
+For the first time, the default syntax highlighter has changed for the
+`highlight` tag and for backtick code blocks. Instead of [Pygments.rb](https://github.com/tmm1/pygments.rb),
+it's now [Rouge](http://rouge.jneen.net/). If you were using the `highlight` tag with certain
+options, such as `hl_lines`, they may not be available when using Rouge. To
+go back to using Pygments, set `highlighter: pygments` in your
+`_config.yml` file and run `gem install pygments.rb` or add
+`gem 'pygments.rb'` to your project's `Gemfile`.
+
+### Relative Permalink support removed
+
+In Jekyll 3 and above, relative permalinks have been deprecated. If you
+created your site using Jekyll 2 and below, you may receive the following
+error when trying to **serve** or **build**:
+
+{% highlight text %}
+Since v3.0, permalinks for pages in subfolders must be relative to the site
+source directory, not the parent directory. Check
+http://jekyllrb.com/docs/upgrading/ for more info.
+{% endhighlight %}
+
+This can be fixed by removing the following line from your `_config.yml` file:
+
+{% highlight yaml %}
+relative_permalinks: true
+{% endhighlight %}
+
+### Permalinks no longer automatically add a trailing slash
+
+In Jekyll 2, any URL constructed from the `permalink:` field had a trailing slash (`/`) added to it automatically.  Jekyll 3 no longer adds a trailing slash automatically to `permalink:` URLs. This can potentially result in old links to pages returning a 404 error. For example, suppose a page previously contained the YAML `permalink: /:year-:month-:day-:title` that resulted in the URL `example.com/2016-02-01-test/` (notice the trailing slash), Jekyll internally generates a folder named `2016-02-01-test`. In Jekyll 3, the same `permalink:` generate the file `2016-02-01-test.html` and the URL for the same page will be `example.com/2016-02-01-test`, and consequently any links to the old URL will result in a 404 error. In order to maintain the same URLs and avoid this problem, a trailing slash should be added to the `permalink:` field, for example `permalink: /:year-:month-:day-:title/`.
+
+### All my posts are gone! Where'd they go!
+
+Try adding `future: true` to your `_config.yml` file. Are they showing up now? If they are, then you were ensnared by an issue with the way Ruby parses times. Each of your posts is being read in a different timezone than you might expect and, when compared to the computer's current time, is "in the future." The fix for this is to add [a timezone offset](https://en.wikipedia.org/wiki/List_of_UTC_time_offsets) to each post (and make sure you remove `future: true` from your `_config.yml` file). If you're writing from California, for example, you would change this:
+
+{% highlight yaml %}
+---
+date: 2016-02-06 19:32:10
+---
+{% endhighlight %}
+
+to this (note the offset):
+
+{% highlight yaml %}
+---
+date: 2016-02-06 19:32:10 -0800
+---
+{% endhighlight %}
+
+_Did we miss something? Please click "Improve this page" above and add a section. Thanks!_

data/site/_docs/variables.md

@@ -106,7 +106,7 @@ following is a reference of the available data.
         related Posts. By default, these are the ten most recent posts.
         For high quality but slow to compute results, run the
         <code>jekyll</code> command with the <code>--lsi</code> (latent semantic
-        indexing) option. Also note Github pages does not support the <code>lsi</code> option when generating sites.
+        indexing) option. Also note GitHub Pages does not support the <code>lsi</code> option when generating sites.
 
       </p></td>
     </tr>

data/site/_docs/windows.md

@@ -11,9 +11,11 @@ knowledge and lessons that have been unearthed by Windows users.
 ## Installation
 
 Julian Thilo has written up instructions to get
-[Jekyll running on Windows][windows-installation] and it seems to work for most.
-The instructions were written for Ruby 2.0.0, but should work for later versions
-[prior to 2.2][hitimes-issue].
+[Jekyll running on Windows][windows-installation] and it seems to work for most
+people. The instructions were written for Ruby 2.0.0, but should work for later
+versions [prior to 2.2][hitimes-issue].
+
+Alternatively David Burela has written instructions on [how to install Jekyll via Chocolately with 3 command prompt entries](https://davidburela.wordpress.com/2015/11/28/easily-install-jekyll-on-windows-with-3-command-prompt-entries-and-chocolatey/).
 
 ## Encoding
 

data/site/_includes/docs_ul.html

@@ -10,12 +10,8 @@
     {% assign c = "" %}
   {% endif %}
 
-  {% for p in site.docs %}
-    {% if p.url == item_url %}
-      <li class="{{ c }}"><a href="{{ site.url }}{{ p.url }}">{{ p.title }}</a></li>
-      {% break %}
-    {% endif %}
-  {% endfor %}
+  {% assign p = site.docs | where:"url",item_url | first %}
+  <li class="{{ c }}"><a href="{{ site.url }}{{ p.url }}">{{ p.title }}</a></li>
 
 {% endfor %}
 </ul>