Improve data file/source documentation

content/en/about/features.md

@@ -109,7 +109,7 @@ toc: true
 [CommonMark]: https://spec.commonmark.org/current/
 [Content adapters]: /content-management/content-adapters/
 [Content formats]: /content-management/formats/
-[Data]: /templates/data-templates/
+[Data]: /content-management/data-sources/
 [Diagrams]: /content-management/diagrams/
 [GDPR]: https://en.wikipedia.org/wiki/General_Data_Protection_Regulation
 [GitHub Flavored Markdown]: https://github.github.com/gfm/

content/en/content-management/content-adapters.md

@@ -6,8 +6,8 @@ keywords: []
 menu:
   docs:
     parent: content-management
-    weight: 280
-weight: 280
+    weight: 290
+weight: 290
 toc: true
 ---
 

content/en/content-management/data-sources.md

@@ -0,0 +1,122 @@
+---
+title: Data sources
+description: Use local and remote data sources to augment or create content.
+categories: [content management]
+keywords: [data,json,toml,yaml,xml]
+menu:
+  docs:
+    parent: content-management
+    weight: 280
+weight: 280
+toc: true
+aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/,/templates/data-templates/]
+---
+
+Hugo can access and [unmarshal] local and remote data sources including CSV, JSON, TOML, YAML, and XML. Use this data to augment existing content or to create new content.
+
+[unmarshal]: /getting-started/glossary/#unmarshal
+
+A data source might be a file in the data directory, a [global resource], a [page resource], or a [remote resource].
+
+[global resource]: /getting-started/glossary/#global-resource
+[page resource]: /getting-started/glossary/#page-resource
+[remote resource]: /getting-started/glossary/#remote-resource
+
+## Data directory
+
+The data directory in the root of your project may contain one or more data files, in either a flat or nested tree. Hugo merges the data files to create a single data structure, accessible with the `Data` method on a `Site` object.
+
+Hugo also merges data directories from themes and modules into this single data structure, where the data directory in the root of your project takes precedence.
+
+Theme and module authors may wish to namespace their data files to prevent collisions. For example:
+
+```text
+project/
+└── data/
+    └── mytheme/
+        └── foo.json
+```
+
+{{% note %}}
+Do not place CSV files in the data directory. Access CSV files as page, global, or remote resources.
+{{% /note %}}
+
+See the documentation for the [`Data`] method on `Page` object for details and examples.
+
+[`Data`]: /methods/site/data/
+
+## Global resources
+
+Use the `resources.Get` and `transform.Unmarshal` functions to access data files that exist as global resources.
+
+See the [`transform.Unmarshal`](/functions/transform/unmarshal/#global-resource) documentation for details and examples.
+
+## Page resources
+
+Use the `Resources.Get` method on a `Page` object combined with the `transform.Unmarshal` function to access data files that exist as page resources.
+
+See the [`transform.Unmarshal`](/functions/transform/unmarshal/#page-resource) documentation for details and examples.
+
+## Remote resources
+
+Use the `resources.GetRemote` and `transform.Unmarshal` functions to access remote data.
+
+See the [`transform.Unmarshal`](/functions/transform/unmarshal/#remote-resource) documentation for details and examples.
+
+## Augment existing content
+
+Use data sources to augment existing content. For example, create a shortcode to render an HTML table from a global CSV resource.
+
+{{< code file=assets/pets.csv >}}
+"name","type","breed","age"
+"Spot","dog","Collie","3"
+"Felix","cat","Malicious","7"
+{{< /code >}}
+
+{{< code file=content/example.md lang=text >}}
+{{</* csv-to-table "pets.csv" */>}}
+{{< /code >}}
+
+{{< code file=layouts/shortcodes/csv-to-table.html >}}
+{{ with $file := .Get 0 }}
+  {{ with resources.Get $file }}
+    {{ with . | transform.Unmarshal }}
+      <table>
+        <thead>
+          <tr>
+            {{ range index . 0 }}
+              <th>{{ . }}</th>
+            {{ end }}
+          </tr>
+        </thead>
+        <tbody>
+          {{ range after 1 . }}
+            <tr>
+              {{ range . }}
+                <td>{{ . }}</td>
+              {{ end }}
+            </tr>
+          {{ end }}
+        </tbody>
+      </table>
+    {{ end }}
+  {{ else }}
+    {{ errorf "The %q shortcode was unable to find %s. See %s" $.Name $file $.Position }}
+  {{ end }}
+{{ else }}
+  {{ errorf "The %q shortcode requires one positional parameter, the path to the CSV file relative to the assets directory. See %s" .Name .Position }}
+{{ end }}
+{{< /code >}}
+
+Hugo renders this to:
+
+name|type|breed|age
+:--|:--|:--|:--
+Spot|dog|Collie|3
+Felix|cat|Malicious|7
+
+## Create new content
+
+Use [content adapters] to create new content.
+
+[content adapters]: /content-management/content-adapters/

content/en/getting-started/directory-structure.md

@@ -91,7 +91,7 @@ content
 : The `content` directory contains the markup files (typically Markdown) and page resources that comprise the content of your site. See [details](/content-management/organization/).
 
 data
-: The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/templates/data-templates/).
+: The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/content-management/data-sources/).
 
 i18n
 : The `i18n` directory contains translation tables for multilingual sites. See [details](/content-management/multilingual/).

content/en/methods/site/Data.md

@@ -101,7 +101,13 @@ To find a fiction book by ISBN:
 {{ end }}
 ```
 
-In the template examples above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function:
+In the template examples above, each of the keys is a valid [identifier]. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function. For example:
+
+[identifier]: /getting-started/glossary/#identifier
+
+```go-html-template
+{{ index .Site.Data.books "historical-fiction" }}
+```
 
 [`index`]: /functions/collections/indexfunction/
 [chaining]: /getting-started/glossary/#chain