HUGO

  • News
  • Docs
  • Themes
  • Showcase
  • Community
  • GitHub
gohugoio Star
  • About
    • In this section
    • Introduction
    • Features
    • Privacy
    • Security
    • License
  • Installation
    • In this section
    • macOS
    • Linux
    • Windows
    • BSD
  • Getting started
    • In this section
    • Quick start
    • Basic usage
    • Directory structure
    • Configuration
    • Configure markup
    • Glossary of terms
    • External learning resources
  • Quick reference
    • In this section
    • Emojis
    • Functions
    • Methods
    • Page collections
  • Content management
    • In this section
    • Organization
    • Page bundles
    • Content formats
    • Front matter
    • Build options
    • Page resources
    • Image processing
    • Shortcodes
    • Related content
    • Sections
    • Content types
    • Archetypes
    • Taxonomies
    • Summaries
    • Links and cross references
    • URL management
    • Menus
    • Static files
    • Comments
    • Multilingual
    • Markdown attributes
    • Syntax highlighting
    • Diagrams
    • Mathematics
    • Content adapters
  • Templates
    • In this section
    • Introduction
    • Template lookup order
    • Base templates and blocks
    • Single page templates
    • List templates
    • Homepage template
    • Section templates
    • Taxonomy templates
    • Pagination
    • Content view templates
    • Partial templates
    • Shortcode templates
    • Menu templates
    • Data templates
    • RSS templates
    • Sitemap templates
    • Embedded templates
    • Custom output formats
    • 404 template
    • Robots.txt
  • Functions
    • In this section
    • cast
    • collections
    • compare
    • crypto
    • data
    • debug
    • diagrams
    • encoding
    • fmt
    • global
    • go template
    • hugo
    • images
    • inflect
    • js
    • lang
    • math
    • openapi3
    • os
    • partials
    • path
    • reflect
    • resources
    • safe
    • strings
    • templates
    • time
    • transform
    • urls
  • Methods
    • In this section
    • Duration
    • Menu
    • Menu entry
    • Page
    • Pages
    • Resource
    • Shortcode
    • Site
    • Taxonomy
    • Time
  • Render hooks
    • In this section
    • Introduction
    • Code blocks
    • Headings
    • Images
    • Links
  • Hugo Modules
    • In this section
    • Configure Hugo modules
    • Use Hugo Modules
    • Theme components
  • Hugo Pipes
    • In this section
    • Introduction
    • Transpile Sass to CSS
    • PostCSS
    • PostProcess
    • JavaScript building
    • Babel
    • Asset minification
    • Concatenating assets
    • Fingerprinting and SRI hashing
    • Resource from string
    • Resource from template
  • CLI
  • Troubleshooting
    • In this section
    • Audit
    • Logging
    • Inspection
    • Deprecation
    • Performance
    • FAQs
  • Developer tools
    • In this section
    • Editor plugins
    • Front-ends
    • Search
    • Migrations
    • Other projects
  • Hosting and deployment
    • In this section
    • Hugo Deploy
    • Deploy with Rclone
    • Deploy with Rsync
    • Host on 21YunBox
    • Host on AWS Amplify
    • Host on Azure Static Web Apps
    • Host on Cloudflare Pages
    • Host on Firebase
    • Host on GitHub Pages
    • Host on GitLab Pages
    • Host on KeyCDN
    • Host on Netlify
    • Host on Render
  • Contribute
    • In this section
    • Development
    • Documentation
    • Themes
  • Maintenance
TEMPLATES

Data templates

In addition to Hugo’s built-in variables, you can specify your own custom data in templates or shortcodes that pull from both local and dynamic sources.

Hugo supports loading data from YAML, JSON, XML, and TOML files located in the data directory at the root of your Hugo project.

The data directory

The data directory should store additional data for Hugo to use when generating your site.

Data files are not for generating standalone pages. They should supplement content files by:

  • Extending the content when the front matter fields grow out of control, or
  • Showing a larger dataset in a template (see the example below).

In both cases, it’s a good idea to outsource the data in their (own) files.

These files must be YAML, JSON, XML, or TOML files (using the .yml, .yaml, .json, .xml, or .toml extension). The data will be accessible as a map in the .Site.Data variable.

To access the data using the site.Data.filename notation, the file name must begin with an underscore or a Unicode letter, followed by zero or more underscores, Unicode letters, or Unicode digits. For example:

  • 123.json - Invalid
  • x123.json - Valid
  • _123.json - Valid

To access the data using the index function, the file name is irrelevant. For example:

Data file Template code
123.json {{ index .Site.Data "123" }}
x123.json {{ index .Site.Data "x123" }}
_123.json {{ index .Site.Data "_123" }}
x-123.json {{ index .Site.Data "x-123" }}

Data files in themes

Data Files can also be used in themes.

However, note that the theme data files are merged with the project directory taking precedence. That is, Given two files with the same name and relative path, the data in the file in the root project data directory will override the data from the file in the themes/<THEME>/data directory for keys that are duplicated).

Therefore, theme authors should be careful not to include data files that could be easily overwritten by a user who decides to customize a theme. For theme-specific data items that shouldn’t be overridden, it can be wise to prefix the folder structure with a namespace; e.g. mytheme/data/<THEME>/somekey/.... To check if any such duplicate exists, run hugo with the -v flag.

The keys in the map created with data templates from data files will be a dot-chained set of path, filename, and key in the file (if applicable).

This is best explained with an example:

Examples

Jaco Pastorius’ Solo Discography

Jaco Pastorius was a great bass player, but his solo discography is short enough to use as an example. John Patitucci is another bass giant.

The example below is a bit contrived, but it illustrates the flexibility of data Files. This example uses TOML as its file format with the two following data files:

  • data/jazz/bass/jacopastorius.toml
  • data/jazz/bass/johnpatitucci.toml

jacopastorius.toml contains the content below. johnpatitucci.toml contains a similar list:

data/jazz/bass/jacopastorius.
     
discography:
- 1974 - Modern American Music … Period! The Criteria Sessions
- 1974 - Jaco
- 1976 - Jaco Pastorius
- 1981 - Word of Mouth
- 1981 - The Birthday Concert (released in 1995)
- 1982 - Twins I & II (released in 1999)
- 1983 - Invitation
- 1986 - Broadway Blues (released in 1998)
- 1986 - Honestly Solo Live (released in 1990)
- 1986 - Live In Italy (released in 1991)
- 1986 - Heavy'n Jazz (released in 1992)
- 1991 - Live In New York City, Volumes 1-7.
- 1999 - Rare Collection (compilation)
- '2003 - Punk Jazz: The Jaco Pastorius Anthology (compilation)'
- 2007 - The Essential Jaco Pastorius (compilation)
discography = ['1974 - Modern American Music … Period! The Criteria Sessions', '1974 - Jaco', '1976 - Jaco Pastorius', '1981 - Word of Mouth', '1981 - The Birthday Concert (released in 1995)', '1982 - Twins I & II (released in 1999)', '1983 - Invitation', '1986 - Broadway Blues (released in 1998)', '1986 - Honestly Solo Live (released in 1990)', '1986 - Live In Italy (released in 1991)', "1986 - Heavy'n Jazz (released in 1992)", '1991 - Live In New York City, Volumes 1-7.', '1999 - Rare Collection (compilation)', '2003 - Punk Jazz: The Jaco Pastorius Anthology (compilation)', '2007 - The Essential Jaco Pastorius (compilation)']
{
   "discography": [
      "1974 - Modern American Music … Period! The Criteria Sessions",
      "1974 - Jaco",
      "1976 - Jaco Pastorius",
      "1981 - Word of Mouth",
      "1981 - The Birthday Concert (released in 1995)",
      "1982 - Twins I \u0026 II (released in 1999)",
      "1983 - Invitation",
      "1986 - Broadway Blues (released in 1998)",
      "1986 - Honestly Solo Live (released in 1990)",
      "1986 - Live In Italy (released in 1991)",
      "1986 - Heavy'n Jazz (released in 1992)",
      "1991 - Live In New York City, Volumes 1-7.",
      "1999 - Rare Collection (compilation)",
      "2003 - Punk Jazz: The Jaco Pastorius Anthology (compilation)",
      "2007 - The Essential Jaco Pastorius (compilation)"
   ]
}

The list of bass players can be accessed via .Site.Data.jazz.bass, a single bass player by adding the file name without the suffix, e.g. .Site.Data.jazz.bass.jacopastorius.

You can now render the list of recordings for all the bass players in a template:

{{ range $.Site.Data.jazz.bass }}
  {{ partial "artist.html" . }}
{{ end }}

And then in the partials/artist.html:

<ul>
{{ range .discography }}
  <li>{{ . }}</li>
{{ end }}
</ul>

Discover a new favorite bass player? Just add another .toml file in the same directory.

Accessing named values in a data file

Assume you have the following data structure in your user0123 data file located directly in data/:

data/user0123.
     
Achievements:
- Can create a Key, Value list from Data File
- Learns Hugo
- Reads documentation
Name: User0123
Short Description: He is a **jolly good** fellow.
Achievements = ['Can create a Key, Value list from Data File', 'Learns Hugo', 'Reads documentation']
Name = 'User0123'
'Short Description' = 'He is a **jolly good** fellow.'
{
   "Achievements": [
      "Can create a Key, Value list from Data File",
      "Learns Hugo",
      "Reads documentation"
   ],
   "Name": "User0123",
   "Short Description": "He is a **jolly good** fellow."
}

You can use the following code to render the Short Description in your layout:

<div>Short Description of {{ .Site.Data.user0123.Name }}: <p>{{ index .Site.Data.user0123 "Short Description" | markdownify }}</p></div>

Note the use of the markdownify function. This will send the description through the Markdown rendering engine.

Remote data

Retrieve remote data using these template functions:

  • resources.GetRemote (recommended)
  • data.GetCSV
  • data.GetJSON

LiveReload with data files

There is no chance to trigger a LiveReload when the content of a URL changes. However, when a local file changes (i.e., data/* and themes/<THEME>/data/*), a LiveReload will be triggered. Note too that because downloading data takes a while, Hugo stops processing your Markdown files until the data download has been completed.

If you change any local file and the LiveReload is triggered, Hugo will read the data-driven (URL) content from the cache. If you have disabled the cache (i.e., by running the server with hugo server --ignoreCache), Hugo will re-download the content every time LiveReload triggers. This can create huge traffic. You may reach API limits quickly.

Examples of data-driven content

  • Photo gallery JSON powered: https://github.com/pcdummy/hugo-lightslider-example.
  • GitHub Starred Repositories in a post using data-driven content in a custom short code.
  • Importing exported social media data from popular services using https://github.com/ttybitnik/diego.

Specs for data formats

  • TOML Spec
  • YAML Spec
  • JSON Spec
  • CSV Spec
  • XML Spec

See also

  • Configure Hugo
  • Front matter
  • Babel
  • Code block render hooks
  • Colors

On this page

  • The data directory
  • Data files in themes
  • Examples
  • Remote data
  • LiveReload with data files
  • Examples of data-driven content
  • Specs for data formats
Last updated: May 12, 2024: Remove references to symlinks (f31741b47)
Improve this page
By the Hugo Authors
Hugo Logo
  • File an Issue
  • Get Help
  • @GoHugoIO
  • @spf13
  • @bepsays

Netlify badge

 

Hugo Sponsors

 

The Hugo logos are copyright © Steve Francia 2013–2024.

The Hugo Gopher is based on an original work by Renée French.

  • News
  • Docs
  • Themes
  • Showcase
  • Community
  • GitHub
  • About
  • Installation
  • Getting started
  • Quick reference
  • Content management
  • Templates
  • Functions
  • Methods
  • Render hooks
  • Hugo Modules
  • Hugo Pipes
  • CLI
  • Troubleshooting
  • Developer tools
  • Hosting and deployment
  • Contribute
  • Maintenance