From 03fff880ecfb971624e6fba1e1d8ffc014b6601a Mon Sep 17 00:00:00 2001
From: bep <bjorn.erik.pedersen@gmail.com>
Date: Mon, 9 Feb 2015 16:52:52 +0100
Subject: [PATCH] Add docs for Data Files

Fixes #887
---
 docs/content/extras/datafiles.md          | 68 +++++++++++++++++++++++
 docs/content/extras/scratch.md            |  2 +-
 docs/content/overview/source-directory.md |  3 +
 docs/content/templates/variables.md       |  1 +
 4 files changed, 73 insertions(+), 1 deletion(-)
 create mode 100644 docs/content/extras/datafiles.md

diff --git a/docs/content/extras/datafiles.md b/docs/content/extras/datafiles.md
new file mode 100644
index 000000000..cb7322edc
--- /dev/null
+++ b/docs/content/extras/datafiles.md
@@ -0,0 +1,68 @@
+---
+aliases:
+- /doc/scratch/
+date: 2015-01-22
+menu:
+  main:
+    parent: extras
+next: /extras/highlighting
+prev: /extras/scratch
+title: Data Files
+weight: 90
+---
+
+In addition to the [built-in variables](/templates/variables/) available from Hugo, you can specify your own custom data that can be accessed via templates or shortcodes.
+
+Hugo supports loading data from [YAML](http://yaml.org/), [JSON](http://www.json.org/), and [TOML](https://github.com/toml-lang/toml) files located in the `data` directory.
+
+**It even works with [LiveReload](/extras/livereload/).**
+
+## The Data Folder
+
+As explained in [Source Organization](/overview/source-directory/), the `data` folder is where you can store additional data for Hugo to use when generating your site. These files must be YAML, JSON or TOML files (using either the `.yml`, `.yaml`, `.json` or `toml` extension) and the data will be accessible as a `map` in `.Site.Data`.
+
+**The keys in this map will be a dot chained set of _path_, _filename_ and _key_ in file (if applicable).** 
+
+This is best explained with an example:
+
+## Example: Jaco Pastorius' Solo Discography
+
+[Jaco Pastorius](http://en.wikipedia.org/wiki/Jaco_Pastorius_discography) was a great bass player, but his solo discography is short enough to use as an example.
+
+The example below uses TOML as file format.
+
+Given the file `data/jazz/bass/jacopastorius.toml` with the content below:
+
+```
+discography = [
+"1974 – Modern American Music … Period! The Criteria Sessions",
+"1974 – Jaco",
+"1976 - Jaco Pastorius",
+"1981 - Word of Mouth",
+"1981 - The Birthday Concert (released in 1995)",
+"1982 - Twins I & II (released in 1999)",
+"1983 - Invitation",
+"1986 - Broadway Blues (released in 1998)",
+"1986 - Honestly Solo Live (released in 1990)",
+"1986 - Live In Italy (released in 1991)",
+"1986 - Heavy'n Jazz (released in 1992)",
+"1991 - Live In New York City, Volumes 1-7.",
+"1999 - Rare Collection (compilation)",
+"2003 - Punk Jazz: The Jaco Pastorius Anthology (compilation)",
+"2007 - The Essential Jaco Pastorius (compilation)" 
+]
+```
+
+This list can be accessed via `.Site.Data.jazz.bass.jacopastorius.discography`.
+
+You can now render the list of recordings in a template:
+
+```
+<ul>
+{{ range $.Site.Data.jazz.bass.jacopastorius.discography }}
+  <li>{{ . }}</li>
+{{ end }}
+</ul>
+```
+
+
diff --git a/docs/content/extras/scratch.md b/docs/content/extras/scratch.md
index 578b1c354..e3c1d9f40 100644
--- a/docs/content/extras/scratch.md
+++ b/docs/content/extras/scratch.md
@@ -5,7 +5,7 @@ date: 2015-01-22
 menu:
   main:
     parent: extras
-next: /extras/highlighting
+next: /extras/datafiles
 prev: /extras/pagination
 title: Scratch
 weight: 80
diff --git a/docs/content/overview/source-directory.md b/docs/content/overview/source-directory.md
index c4ff3e544..f0c0e8a00 100644
--- a/docs/content/overview/source-directory.md
+++ b/docs/content/overview/source-directory.md
@@ -20,6 +20,7 @@ The top level of a source directory will typically have the following elements:
 
     ▸ archetypes/
     ▸ content/
+    ▸ data/
     ▸ layouts/
     ▸ static/
     ▸ themes/
@@ -28,6 +29,7 @@ The top level of a source directory will typically have the following elements:
 Learn more about the different directories and what their purpose is:
 
 * [config](/overview/configuration/)
+* [data](/extras/datafiles/)
 * [archetypes](/content/archetypes/)
 * [content](/content/organization/)
 * [layouts](/layout/overview/)
@@ -50,6 +52,7 @@ An example directory may look like:
     |   └── quote
     |   |   ├── first.md
     |   |   └── second.md
+    ├── data
     ├── layouts
     |   ├── _default
     |   |   ├── single.html
diff --git a/docs/content/templates/variables.md b/docs/content/templates/variables.md
index 75764e80b..5e5d34638 100644
--- a/docs/content/templates/variables.md
+++ b/docs/content/templates/variables.md
@@ -109,6 +109,7 @@ Also available is `.Site` which has the following:
 **.Site.LastChange** A string representing the last time content has been updated.<br>
 **.Site.Permalinks** A string to override the default permalink format. Defined in the site configuration.<br>
 **.Site.BuildDrafts** A boolean (Default: false) to indicate whether to build drafts. Defined in the site configuration.<br>
+**.Site.Data**  Custom data, see [Data Files](/extras/datafiles/).<br>
 
 ## Hugo Variables