Merge pull request #3638 from adunning/patch-1

Merge pull request 3638

site/_docs/collections.md

@@ -37,6 +37,17 @@ collections:
     foo: bar
 {% endhighlight %}
 
+Default attributes can also be set for a collection:
+
+{% highlight yaml %}
+defaults:
+  - scope:
+      path: ""
+      type: my_collection
+    values:
+      layout: page
+{% endhighlight %}
+
 ### Step 2: Add your content
 
 Create a corresponding folder (e.g. `<source>/_my_collection`) and add
@@ -203,7 +214,7 @@ you specified in your `_config.yml` (if present) and the following information:
       </td>
       <td>
         <p>
-          The path to the collections's source directory, relative to the site
+          The path to the collection's source directory, relative to the site
           source.
         </p>
       </td>
@@ -319,3 +330,47 @@ file, each document has the following attributes:
   </tbody>
 </table>
 </div>
+
+## Accessing Collection Attributes
+
+Attributes from the YAML front matter can be accessed as data anywhere in the site.  Using the above example for configuring a collection as `site.albums`, one might have front matter in an individual file structured as follows (which must use a supported markup format, and cannot cannot be saved with a `.yaml` extension or the like):
+
+{% highlight yaml %}
+title: "Josquin: Missa De beata virgine and Missa Ave maris stella"
+artist: "The Tallis Scholars"
+director: "Peter Phillips"
+works:
+  - title: "Missa De beata virgine"
+    composer: "Josquin des Prez"
+    tracks:
+      - title: "Kyrie"
+        duration: "4:25"
+      - title: "Gloria"
+        duration: "9:53"
+      - title: "Credo"
+        duration: "9:09"
+      - title: "Sanctus & Benedictus"
+        duration: "7:47"
+      - title: "Agnus Dei I, II & III"
+        duration: "6:49"
+{% endhighlight %}
+
+Every album in the collection could be listed on a single page with a template:
+
+{% highlight html %}
+{% raw %}
+{% for album in site.albums %}
+  <h2>{{ album.title }}</h2>
+  <p>Performed by {{ album.artist }}{% if album.director %}, directed by {{ album.director }}{% endif %}</p>
+  {% for work in album.works %}
+    <h3>{{ work.title }}</h3>
+    <p>Composed by {{ work.composer }}</p>
+    <ul>
+    {% for track in work.tracks %}
+      <li>{{ track.title }} ({{ track.duration }})</li>
+    {% endfor %}
+    </ul>
+  {% endfor %}
+{% endfor %}
+{% endraw %}
+{% endhighlight %}