blob: b78caddec5e1349c75b2529145787d9d6b434798 (
plain) (
blame)
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
|
---
title: Data
description: Returns a data structure composed from the files in the data directory.
categories: []
keywords: []
action:
related:
- functions/collections/IndexFunction
- functions/transform/Unmarshal
- functions/collections/Where
- functions/collections/Sort
returnType: map
signatures: [SITE.Data]
---
Use the `Data` method on a `Site` object to access data within the data directory, or within any directory [mounted] to the data directory. Supported data formats include JSON, TOML, YAML, and XML.
[mounted]: /hugo-modules/configuration/#module-configuration-mounts
{{% note %}}
Although Hugo can unmarshal CSV files with the [`transform.Unmarshal`] function, do not place CSV files in the data directory. You cannot access data within CSV files using this method.
[`transform.Unmarshal`]: /functions/transform/unmarshal
{{% /note %}}
Consider this data directory:
```text
data/
├── books/
│ ├── fiction.yaml
│ └── nonfiction.yaml
├── films.json
├── paintings.xml
└── sculptures.toml
```
And these data files:
{{< code file=data/books/fiction.yaml lang=yaml >}}
- title: The Hunchback of Notre Dame
author: Victor Hugo
isbn: 978-0140443530
- title: Les Misérables
author: Victor Hugo
isbn: 978-0451419439
{{< /code >}}
{{< code file=data/books/nonfiction.yaml lang=yaml >}}
- title: The Ancien Régime and the Revolution
author: Alexis de Tocqueville
isbn: 978-0141441641
- title: Interpreting the French Revolution
author: François Furet
isbn: 978-0521280495
{{< /code >}}
Access the data by [chaining] the [identifiers]:
```go-html-template
{{ range $category, $books := .Site.Data.books }}
<p>{{ $category | title }}</p>
<ul>
{{ range $books }}
<li>{{ .title }} ({{ .isbn }})</li>
{{ end }}
</ul>
{{ end }}
```
Hugo renders this to:
```html
<p>Fiction</p>
<ul>
<li>The Hunchback of Notre Dame (978-0140443530)</li>
<li>Les Misérables (978-0451419439)</li>
</ul>
<p>Nonfiction</p>
<ul>
<li>The Ancien Régime and the Revolution (978-0141441641)</li>
<li>Interpreting the French Revolution (978-0521280495)</li>
</ul>
```
To limit the listing to fiction, and sort by title:
```go-html-template
<ul>
{{ range sort .Site.Data.books.fiction "title" }}
<li>{{ .title }} ({{ .author }})</li>
{{ end }}
</ul>
```
To find a fiction book by ISBN:
```go-html-template
{{ range where .Site.Data.books.fiction "isbn" "978-0140443530" }}
<li>{{ .title }} ({{ .author }})</li>
{{ 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:
[`index`]: /functions/collections/indexfunction
[chaining]: /getting-started/glossary/#chain
[identifiers]: /getting-started/glossary/#identifier
|
