Using Local Data Files

The data directory can hold structured data files in YAML, JSON, or TOML formats that you can use in your layouts to display content. You could write these data files by hand or extract them from other sources.

Let’s try this feature out and use it to add social media profile information to the contact page of the site. Instead of embedding your social media accounts in your layout directly, you’ll define them in a JSON file. Then in your layout, you’ll load the file and iterate over its contents and display the data.

Create the file socialmedia.json in the data directory of your site. In the new file, create an accounts property with an array of accounts. In the array, represent each account as an object with a name and url property, like this:

Save the file once you’ve entered in your accounts.

To use this data file, you must use a layout to read the file in and use it. Content pages can’t directly include dynamic content. In ​Using a Shortcode to Process Images​, you’ll learn how to make functions you can include in your content pages that can get dynamic content. For this example, you’ll make a specific layout for the contact page of the site, instead of relying on the default single.html layout.

Add this new layout to the site’s layouts directory, rather than as part of the theme, since this is a specific customization. You can incorporate this into the theme later if you find it useful. Create the file layouts/_default/contact.html and add the following boilerplate to define the main block and display the title and content:

Then, right below the {{ .Content }} line, add this code, which loads the data and iterates over it:

Save the file. The layout you created won’t override the default single page layout because it’s not associated with a specific type of content. When you created a layout for projects, Hugo automatically associated the layout with all content within the projects folder. In this case, there’s no association like that, so you have to explicitly assign the layout file to the contact.md Markdown file. Open content/contact.md and specify the contact layout in the page’s front matter by adding the following code:

Save the file, fire up the development server with hugo server, visit http://localhost:1313/contact in your browser. Your social media links are now displayed on the page:

Sometimes the data you want comes from an external site. Let’s look at how to handle that.