Data

Returns a data structure composed from the files in the data directory.

Syntax

SITE.Data

Returns

map

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.

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.

Consider this data directory:

data/
├── books/
│   ├── fiction.yaml
│   └── nonfiction.yaml
├── films.json
├── paintings.xml
└── sculptures.toml

And these data files:

data/books/fiction.yaml

- title: The Hunchback of Notre Dame
  author: Victor Hugo
  isbn: 978-0140443530
- title: Les Misérables
  author: Victor Hugo
  isbn: 978-0451419439

data/books/nonfiction.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

Access the data by chaining the identifiers:

{{ range $category, $books := .Site.Data.books }}
  <p>{{ $category | title }}</p>
  <ul>
    {{ range $books }}
      <li>{{ .title }} ({{ .isbn }})</li>
    {{ end }}
  </ul>
{{ end }}

Hugo renders this to:

<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:

<ul>
  {{ range sort .Site.Data.books.fiction "title" }}
    <li>{{ .title }} ({{ .author }})</li>
  {{ end }}
</ul>

To find a fiction book by ISBN:

{{ 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. For example:

{{ index .Site.Data.books "historical-fiction" }}

Last updated: March 8, 2025 : content: Replace note shortcode calls with blockquote alerts (c540e6d29)

Improve this page