Merge pull request #1503 from swanson/add-docs-for-data-feature

Add docs for new Data Files feature

site/_includes/docs_contents.html

@@ -3,7 +3,7 @@
     <h4>Getting Started</h4>
     {% include docs_ul.html items='home quickstart installation usage structure configuration' %}
     <h4>Your Content</h4>
-    {% include docs_ul.html items='frontmatter posts drafts pages variables migrations' %}
+    {% include docs_ul.html items='frontmatter posts drafts pages variables datafiles migrations' %}
     <h4>Customization</h4>
     {% include docs_ul.html items='templates permalinks pagination plugins extras' %}
     <h4>Deployment</h4>

site/_includes/docs_contents_mobile.html

@@ -5,7 +5,7 @@
       {% include docs_option.html items='home quickstart installation usage structure configuration' %}
     </optgroup>
     <optgroup label="Your Content">
-      {% include docs_option.html items='frontmatter posts drafts pages variables migrations' %}
+      {% include docs_option.html items='frontmatter posts drafts pages variables datafiles migrations' %}
     </optgroup>
     <optgroup label="Customization">
       {% include docs_option.html items='templates permalinks pagination plugins extras' %}

site/docs/datafiles.md

@@ -0,0 +1,63 @@
+---
+layout: docs
+title: Data Files
+prev_section: variables
+next_section: migrations
+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).
+
+Jekyll supports loading data from [YAML](http://yaml.org/) files located in the 
+`_data` directory.
+
+This powerful features allows you to avoid repetition in your templates and to
+set site specific options without changing `_config.yml`. 
+
+Plugins/themes can also leverage Data Files to set configuration variables.
+
+## The Data Folder
+
+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`
+extension) and they will be accessible via `site.data`.
+
+## Example: List of members
+
+Here is a basic example of using Data Files to avoid copy-pasting large chunks of
+code in your Jekyll templates:
+
+In `_data/members.yml`:
+
+{% highlight yaml %}
+- name: Tom Preston-Werner
+  github: mojombo
+
+- name: Parker Moore
+  github: parkr
+
+- name: Liu Fengyun
+  github: liufengyun
+{% endhighlight %}
+
+This data can be accessed via `site.data.members` (notice that the filename
+determines the variable name).
+
+You can now render the list of members in a template:
+
+{% highlight html %}
+{% raw %}
+<ul>
+{% for member in site.data.members %}
+  <li>
+    <a href="https://github.com/{{ member.github }}">
+      {{ member.name }}
+    </a>
+  </li>
+{% end %}
+</ul>
+{% endraw %}
+{% endhighlight %}

site/docs/migrations.md

@@ -1,7 +1,7 @@
 ---
 layout: docs
 title: Blog migrations
-prev_section: variables
+prev_section: datafiles
 next_section: templates
 permalink: /docs/migrations/
 ---

site/docs/variables.md

@@ -2,7 +2,7 @@
 layout: docs
 title: Variables
 prev_section: pages
-next_section: migrations
+next_section: datafiles
 permalink: /docs/variables/
 ---