Data sources

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.

A data source might be a file in the data directory, a [global resource], a [page resource], or a [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:

project/
└── data/
    └── mytheme/
        └── foo.json

See the documentation for the [Data] method on a Site object for details and examples.

Global resources #

Use the resources.Get and transform.Unmarshal functions to access data files that exist as global resources.

See the transform.Unmarshal 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 documentation for details and examples.

Remote resources #

Use the resources.GetRemote and transform.Unmarshal functions to access remote data.

See the transform.Unmarshal 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.

"name","type","breed","age"
"Spot","dog","Collie","3"
"Felix","cat","Malicious","7"

{{< csv-to-table "pets.csv" >}}

{{ 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 }}

Hugo renders this to:

Create new content #

Use [content adapters] to create new content.