1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
---
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.
{{% note %}}
Hugo reads the combined data structure into memory and keeps it there for the entire build. For data that is infrequently accessed, use global or page resources instead.
{{% /note %}}
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 a `Site` 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 argument, 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/
|
