jekyll 2.0.3 → 2.1.0

data/site/docs/configuration.md

@@ -278,40 +278,111 @@ before your site is served.
 
 ## Frontmatter defaults
 
-You can set default values for your [YAML frontmatter](../frontmatter/) variables
-in your configuration. This way, you can for example set default layouts or define
-defaults for your custom variables. Of course, any variable actually specified in
-the front matter overrides the defaults.
+Using [YAML front-matter](../frontmatter/) is one way that you can specify configuration in the pages and posts for your site. Setting things like a default layout, or customizing the title, or specifying a more precise date/time for the post can all be added to your page or post front-matter.
 
-All defaults go under the `defaults` key, which holds a list of scope-values combinations ("default sets").
-The `scope` key defines for which files the defaults apply, limiting them by their source file `path` and
-optionally by their `type` (`page`, `post` or `draft`). The `values` key holds the actual list of defaults.
+Often times, you will find that you are repeating a lot of configuration options. Setting the same layout in each file, adding the same category - or categories - to a post, etc. You can even add custom variables like author names, which might be the same for the majority of posts on your blog.
+
+Instead of repeating this configuration each time you create a new post or page, Jekyll provides a way to set these defaults in the site configuration. To do this, you can specify  site-wide defaults using the `defaults` key in the `_config.yml` file in your projects root directory.
+
+The `defaults` key holds an array of scope/values pairs that define what defaults should be set for a particular file path, and optionally, a file type in that path.
+
+Let's say that you want to add a default layout to all pages and posts in your site. You would add this to your `_config.yml` file:
 
-For example:
 {% highlight yaml %}
 defaults:
   -
     scope:
-      path: "" # empty string for all files
+      path: "" # an empty string here means all files in the project
     values:
-      layout: "my-site"
+      layout: "default"
+{% endhighlight %}
+
+Here, we are scoping the `values` to any file that exists in the scopes path. Since the path is set as an empty string, it will apply to **all files** in your project. You probably don't want to set a layout on every file in your project - like css files, for example - so you can also specify a `type` value under the `scope` key.
+
+{% highlight yaml %}
+defaults:
+  -
+    scope:
+      path: "" # an empty string here means all files in the project
+      type: "post"
+    values:
+      layout: "default"
+{% endhighlight %}
+
+Now, this will only set the layout for files where the type is `post`.
+The different types that are available to you are `page`, `post`, `draft` or any collection in your site. While `type` is optional, you must specify a value for `path` when creating a `scope/values` pair.
+
+As mentioned earlier, you can set multiple scope/values pairs for `defaults`.
+
+{% highlight yaml %}
+defaults:
   -
     scope:
-      path: "about/blog"
+      path: ""
       type: "post"
     values:
-      layout: "meta-blog" # overrides previous default layout
-      author: "Dr. Hyde"
+      layout: "my-site"
+  -
+    scope:
+      path: "projects"
+      type: "page"
+    values:
+      layout: "project" # overrides previous default layout
+      author: "Mr. Hyde"
+      category: "project"
+{% endhighlight %}
+
+With these defaults, all posts would use the `my-site` layout. Any html files that exist in the `projects/` folder will use the `project` layout, if it exists. Those files will also have the `page.author` [liquid variable](../variables/) set to `Mr. Hyde` as well as have the category for the page set to `project`.
+
+{% highlight yaml %}
+collections:
+  - my_collection:
+    output: true
+
+defaults:
+  -
+    scope:
+      path: ""
+      type: "my_collection" # a collection in your site
+    values:
+      layout: "default"
 {% endhighlight %}
 
-With these defaults, all pages and posts would default to the `my-site` layout except for the posts under `about/blog`,
-who would default to the `meta-blog` layout and also have the `page.author` [liquid variable](../variables/) set to `Dr. Hyde` by default.
+In this example the `layout` is set to `default` inside the [collection](../collections) with the name `my_collection`.
 
 ### Precedence
-You can have multiple sets of frontmatter defaults that specify defaults for the same setting. In this case, for each page or post,
-the default set with the more specific scope takes precedence. This way, you can specify defaults for a path like `/site/blog` that would
-override any defaults for `/site`. Also, if the paths are equal, a scope with a specified type is more specific. If two sets are equally
-specific, the bottom-most takes precedence.
+
+Jekyll will apply all of the configuration settings you specify in the `defaults` section of your `_config.yml` file. However, you can choose to override settings from other scope/values pair by specifying a more specific path for the scope.
+
+You can see that in the last example above. First, we set the default layout to `my-site`. Then, using a more specific path, we set the default layout for files in the `projects/` path to `project`. This can be done with any value that you would set in the page or post front-matter.
+
+Finally, if you set defaults in the site configuration by adding a `defaults` section to your `_config.yml` file, you can override those settings in a post or page file. All you need to do is specify the settings in the post or page front-matter. For example:
+
+{% highlight yaml %}
+# In _config.yml
+...
+defaults:
+  -
+    scope:
+      path: "projects"
+      type: "page"
+    values:
+      layout: "project"
+      author: "Mr. Hyde"
+      category: "project"
+...
+{% endhighlight %}
+
+{% highlight yaml %}
+# In projects/foo_project.md
+---
+author: "John Smith"
+layout: "foobar"
+---
+The post text goes here...
+{% endhighlight %}
+
+The `projects/foo_project.md` would have the `layout` set to `foobar` instead of `project` and the `author` set to `John Smith` instead of `Mr. Hyde` when the site is built.
 
 ## Default Configuration
 
@@ -341,7 +412,7 @@ timezone:    nil
 encoding:    nil
 
 future:      true
-show_drafts: nil
+show_drafts: false
 limit_posts: 0
 highlighter: pygments
 
@@ -363,7 +434,6 @@ server:      false    # deprecated
 host:        0.0.0.0
 port:        4000
 baseurl:     ""
-url:         http://localhost:4000
 lsi:         false
 
 maruku:

data/site/docs/continuous-integration.md

@@ -0,0 +1,177 @@
+---
+layout: docs
+title: Continuous Integration
+prev_section: deployment-methods
+next_section: troubleshooting
+permalink: /docs/continuous-integration/
+---
+
+You can easily test your website build against one or more versions of Ruby.
+The following guide will show you how to set up a free build environment on
+[Travis][0], with [GitHub][1] integration for pull requests. Paid
+alternatives exist for private repositories.
+
+[0]: https://travis-ci.org/
+[1]: https://github.com/
+
+## 1. Enabling Travis and GitHub
+
+Enabling Travis builds for your GitHub repository is pretty simple:
+
+1. Go to your profile on travis-ci.org: https://travis-ci.org/profile/username
+2. Find the repository for which you're interested in enabling builds.
+3. Click the slider on the right so it says "ON" and is a dark grey.
+4. Optionally configure the build by clicking on the wrench icon. Further
+   configuration happens in you `.travis.yml` file. More details on that
+   below.
+
+## 2. The Test Script
+
+The simplest test script simply runs `jekyll build` and ensures that Jekyll
+doesn't fail to build the site. It doesn't check the resulting site, but it
+does ensure things are built properly.
+
+When testing Jekyll output, there is no better tool than [html-proofer][2].
+This tool checks your resulting site to ensure all links and images exist.
+Utilize it either with the convenient `htmlproof` command-line executable,
+or write a Ruby script which utilizes the gem.
+
+### The HTML Proofer Executable
+
+{% highlight bash %}
+#!/usr/bin/env bash
+set -e # halt script on error
+
+bundle exec jekyll build
+bundle exec htmlproof ./_site
+{% endhighlight %}
+
+Some options can be specified via command-line switches. Check out the
+`html-proofer` README for more information about these switches, or run
+`htmlproof --help` locally.
+
+### The HTML Proofer Library
+
+You can also invoke `html-proofer` in Ruby scripts (e.g. in a Rakefile):
+
+{% highlight ruby %}
+#!/usr/bin/env ruby
+
+require 'html/proofer'
+HTML::Proofer.new("./_site").run
+{% endhighlight %}
+
+Options are given as a second argument to `.new`, and are encoded in a
+symbol-keyed Ruby Hash. More information about the configuration options,
+check out `html-proofer`'s README file.
+
+[2]: https://github.com/gjtorikian/html-proofer
+
+## 3. Configuring Your Travis Builds
+
+This file is used to configure your Travis builds. Because Jekyll is built
+with Ruby and requires RubyGems to install, we use the Ruby language build
+environment. Below is a sample `.travis.yml` file, and what follows that is
+an explanation of each line.
+
+{% highlight yaml %}
+language: ruby
+rvm:
+- 2.1
+script: ./script/cibuild
+
+# branch whitelist
+branches:
+  only:
+  - gh-pages     # test the gh-pages branch
+  - /pages-(.*)/ # test every branch which starts with "pages-"
+
+env:
+  global:
+  - NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer
+{% endhighlight %}
+
+Ok, now for an explanation of each line:
+
+{% highlight yaml %}
+language: ruby
+{% endhighlight %}
+
+This line tells Travis to use a Ruby build container. It gives your script
+access to Bundler, RubyGems, and and Ruby runtime.
+
+{% highlight yaml %}
+rvm:
+- 2.1
+{% endhighlight %}
+
+RVM is a popular Ruby Version Manager (like rbenv, chruby, etc). This
+directive tells Travis the Ruby version to use when running your test
+script.
+
+{% highlight yaml %}
+script: ./script/cibuild
+{% endhighlight %}
+
+Travis allows you to run any arbitrary shell script to test your site. One
+convention is to put all scripts for your project in the `script`
+directory, and to call your test script `cibuild`. This line is completely
+customizable. If your script won't change much, you can write your test
+incantation here directly:
+
+{% highlight yaml %}
+script: jekyll build && htmlproof ./_site
+{% endhighlight %}
+
+The `script` directive can be absolutely any valid shell command.
+
+{% highlight yaml %}
+# branch whitelist
+branches:
+  only:
+  - gh-pages     # test the gh-pages branch
+  - /pages-(.*)/ # test every branch which starts with "pages-"
+{% endhighlight %}
+
+You want to ensure the Travis builds for your site are being run only on
+the branch or branches which contain your site. One means of ensuring this
+isolation is including a branch whitelist in your Travis configuration
+file. By specifying the `gh-pages` branch, you will ensure the associated
+test script (discussed above) is only executed on site branches. If you use
+a pull request flow for proposing changes, you may wish to enforce a
+convention for your builds such that all branches containing edits are
+prefixed, exemplified above with the `/pages-(.*)/` regular expression.
+
+The `branches` directive is completely optional.
+
+{% highlight yaml %}
+env:
+  global:
+  - NOKOGIRI_USE_SYSTEM_LIBRARIES=true # speeds up installation of html-proofer
+{% endhighlight %}
+
+Using `html-proofer`? You'll want this environment variable. Nokogiri, used
+to parse HTML files in your compiled site, comes bundled with libraries
+which it must compile each time it is installed. Luckily, you can
+dramatically increase the install time of Nokogiri by setting the
+environment variable `NOKOGIRI_USE_SYSTEM_LIBRARIES` to `true`.
+
+## 4. Gotchas
+
+### Exclude `vendor`
+
+Travis bundles all gems in the `vendor` directory on its build servers,
+which Jekyll will mistakenly read and explode on. To avoid this, exclude
+`vendor` in your `_config.yml`:
+
+{% highlight yaml %}
+exclude: [vendor]
+{% endhighlight %}
+
+### Questions?
+
+This entire guide is open-source. Go ahead and [edit it][3] if you have a
+fix or [ask for help][4] if you run into trouble and need some help.
+
+[3]: https://github.com/jekyll/jekyll/edit/master/site/docs/continuous-integration.md
+[4]: https://github.com/jekyll/jekyll-help#how-do-i-ask-a-question

data/site/docs/contributing.md

@@ -11,8 +11,8 @@ following in mind:
 
 * If you're creating a small fix or patch to an existing feature, just a simple
   test will do. Please stay in the confines of the current test suite and use
-  [Shoulda](http://github.com/thoughtbot/shoulda/tree/master) and
-  [RR](http://github.com/btakita/rr/tree/master).
+  [Shoulda](https://github.com/thoughtbot/shoulda/tree/master) and
+  [RR](https://github.com/btakita/rr/tree/master).
 * If it's a brand new feature, make sure to create a new
   [Cucumber](https://github.com/cucumber/cucumber/) feature and reuse steps
   where appropriate. Also, whipping up some documentation in your fork's `site`

data/site/docs/datafiles.md

@@ -8,9 +8,9 @@ permalink: /docs/datafiles/
 
 In addition to the [built-in variables](../variables/) available from Jekyll,
 you can specify your own custom data that can be accessed via the [Liquid
-templating system](http://wiki.github.com/shopify/liquid/liquid-for-designers).
+templating system](https://wiki.github.com/shopify/liquid/liquid-for-designers).
 
-Jekyll supports loading data from [YAML](http://yaml.org/) files located in the
+Jekyll supports loading data from [YAML](http://yaml.org/) and [JSON](http://www.json.org/) files located in the
 `_data` directory.
 
 This powerful feature allows you to avoid repetition in your templates and to
@@ -22,7 +22,7 @@ Plugins/themes can also leverage Data Files to set configuration variables.
 
 As explained on the [directory structure](../structure/) page, the `_data`
 folder is where you can store additional data for Jekyll to use when generating
-your site. These files must be YAML files (using either the `.yml` or `.yaml`
+your site. These files must be YAML files (using either the `.yml`, `.yaml` or `.json`
 extension) and they will be accessible via `site.data`.
 
 ## Example: List of members
@@ -61,3 +61,47 @@ You can now render the list of members in a template:
 </ul>
 {% endraw %}
 {% endhighlight %}
+
+## Example: Organizations
+
+Data files can also be placed in sub-folders of the `_data` folder. Each folder level will be added to a variable's namespace. The example bellow shows how GitHub organizations could be defined separately in a file under the `orgs` folder:
+
+In `_data/orgs/jekyll.yml`:
+
+{% highlight yaml %}
+username: jekyll
+name: Jekyll
+members:
+  - name: Tom Preston-Werner
+    github: mojombo
+
+  - name: Parker Moore
+    github: parkr
+{% endhighlight %}
+
+In `_data/orgs/doeorg.yml`:
+
+{% highlight yaml %}
+username: doeorg
+name: Doe Org
+members:
+  - name: John Doe
+    github: jdoe
+{% endhighlight %}
+
+The organizations can then be accessed via `site.data.orgs`, followed by the file name:
+
+{% highlight html %}
+{% raw %}
+<ul>
+{% for org in site.data.orgs %}
+  <li>
+    <a href="https://github.com/{{ org.username }}">
+      {{ org.name }}
+    </a>
+    ({{ org.members | size }} members)
+  </li>
+{% endfor %}
+</ul>
+{% endraw %}
+{% endhighlight %}

data/site/docs/deployment-methods.md

@@ -80,19 +80,19 @@ Another way to deploy your Jekyll site is to use [Rake](https://github.com/jimwe
 
 ### rsync
 
-Once you’ve generated the `_site` directory, you can easily rsync it using a `tasks/deploy` shell script similar to [this deploy script here](http://github.com/henrik/henrik.nyh.se/blob/master/tasks/deploy). You’d obviously need to change the values to reflect your site’s details. There is even [a matching TextMate command](http://gist.github.com/214959) that will help you run
+Once you’ve generated the `_site` directory, you can easily rsync it using a `tasks/deploy` shell script similar to [this deploy script here](https://github.com/henrik/henrik.nyh.se/blob/master/tasks/deploy). You’d obviously need to change the values to reflect your site’s details. There is even [a matching TextMate command](http://gist.github.com/214959) that will help you run
 this script from within Textmate.
 
 
 ## Rack-Jekyll
 
-[Rack-Jekyll](http://github.com/adaoraul/rack-jekyll/) is an easy way to deploy your site on any Rack server such as Amazon EC2, Slicehost, Heroku, and so forth. It also can run with [shotgun](http://github.com/rtomakyo/shotgun/), [rackup](http://github.com/rack/rack), [mongrel](http://github.com/mongrel/mongrel), [unicorn](http://github.com/defunkt/unicorn/), and [others](https://github.com/adaoraul/rack-jekyll#readme).
+[Rack-Jekyll](https://github.com/adaoraul/rack-jekyll/) is an easy way to deploy your site on any Rack server such as Amazon EC2, Slicehost, Heroku, and so forth. It also can run with [shotgun](https://github.com/rtomakyo/shotgun/), [rackup](https://github.com/rack/rack), [mongrel](https://github.com/mongrel/mongrel), [unicorn](https://github.com/defunkt/unicorn/), and [others](https://github.com/adaoraul/rack-jekyll#readme).
 
 Read [this post](http://blog.crowdint.com/2010/08/02/instant-blog-using-jekyll-and-heroku.html) on how to deploy to Heroku using Rack-Jekyll.
 
 ## Jekyll-Admin for Rails
 
-If you want to maintain Jekyll inside your existing Rails app, [Jekyll-Admin](http://github.com/zkarpinski/Jekyll-Admin) contains drop in code to make this possible. See Jekyll-Admin’s [README](http://github.com/zkarpinski/Jekyll-Admin/blob/master/README) for more details.
+If you want to maintain Jekyll inside your existing Rails app, [Jekyll-Admin](https://github.com/zkarpinski/Jekyll-Admin) contains drop in code to make this possible. See Jekyll-Admin’s [README](https://github.com/zkarpinski/Jekyll-Admin/blob/master/README) for more details.
 
 ## Amazon S3
 

data/site/docs/extras.md

@@ -12,9 +12,7 @@ may want to install, depending on how you plan to use Jekyll.
 ## LaTeX Support
 
 Maruku comes with optional support for LaTeX to PNG rendering via blahtex
-(Version 0.6) which must be in your `$PATH` along with `dvips`. If you need
-Maruku to not assume a fixed location for `dvips`, check out [Remi’s Maruku
-fork](http://github.com/remi/maruku).
+(Version 0.6) which must be in your `$PATH` along with `dvips`.
 
 ## Alternative Markdown Processors
 
@@ -23,8 +21,8 @@ of the other three pre-defined markdown parsers or define your own.
 
 ### RDiscount
 
-If you prefer to use [RDiscount](http://github.com/rtomayko/rdiscount) instead
-of [Maruku](http://github.com/bhollis/maruku) for Markdown, just make sure you have
+If you prefer to use [RDiscount](https://github.com/rtomayko/rdiscount) instead
+of [Maruku](https://github.com/bhollis/maruku) for Markdown, just make sure you have
 it installed:
 
 {% highlight bash %}