Sourcing Content from JSON or YAML

As you work with Gatsby, you might want to source data from a JSON or YAML file directly into a page or component. This guide will cover approaches for those techniques, as well as architecting a Gatsby site from a YAML file.

To follow along with the JSON or YAML data sourcing tips outlined in this guide, you can start by creating a new Gatsby site based on the official hello world starter.

Open up a terminal and run the following command:

Directly import data with YAML

This section starts with YAML data sourcing. If you want to see how to do it using JSON instead, jump to the next section.

Add the YAML content

In your Gatsby project folder, create a directory called content and inside, add a file called My-YAML-Content.yaml with the following content:

Import YAML into the page component

Now that you have something you want to show, the only thing missing is to create a page that will consume the data.

Add a new file called yml-at-buildtime.js inside the pages folder, with the following code:

The above code imports YAML source data as an array, iterates over it with the Array.map method, and renders the data-filled markup through a functional React component.

Directly import data with JSON

In addition to (or instead of) sourcing from YAML, you can use JSON as a data source in a Gatsby site.

Add the JSON content

In your Gatsby project folder, create a directory named content if it doesn’t exist, and then add a new file inside called My-JSON-Content.json with the following content:

Import JSON into the page component

Now that you have JSON data that needs to be shown, all that’s missing is a page to consume it.

Add a new file called json-at-buildtime.js inside the pages folder with the following code:

Similar to the YAML example above, this code snippet shows how to import a JSON file for sourcing data. When imported, the data can be iterated upon with the Array.map method and rendered in a React component.

Out of the box and without any extra configuration, the page will show content sourced from a JSON file.

Build a Gatsby site sourced from YAML

You can also build a fully functional Gatsby site with a page structure sourced from a YAML file.

Add necessary dependencies

For this example, you will need to add an extra dependency so that the file containing the site structure and its contents can be loaded and interpreted safely.

Open your terminal, navigate to the folder containing the Gatsby site, and issue the following command:

This newly added package will be responsible for loading and parsing the YAML file safely.

Add some content

Create a folder named content if it doesn’t exist, and then add a new file inside called index.yaml with the following contents:

The code block above creates a YAML object in which:

  • Each path is a page’s endpoint (the relevant part of its URL).
  • The contents list holds some data to be displayed.
  • The links list holds some endpoints to other pages.

Configure Gatsby pages

Once the dynamic site structure and content exists, you need to tell Gatsby to generate the appropriate pages and display the contents for each one.

If you don’t already have one, create a gatsby-node.js file at the root of the project. Add the following code inside the file:

Breaking down this code excerpt into smaller parts:

  1. Import the js-yaml package you installed earlier.
  2. Load the index.yaml file and parse the content.
  3. Using Gatsby’s createPage() API, create some pages programmatically from the parsed file.
  4. Use the context property to pass your data into the page as a special prop named pageContext, allowing it to be consumed. You can read more about context in creating and modifying pages.

Create a template

To complete the process of rendering the sourced content, you’ll need to create a template for producing dynamic pages from data.

To match the component referenced in gatsby-config.js, create a file called basicTemplate.js in the src/templates/ folder and add the following:

Join the pieces

After parsing a YAML file into data and configuring Gatsby to produce pages with a template, you should have the following file and folder structure:

Running gatsby develop in the terminal and opening a browser window to http://localhost:8000/page1 you’ll see a page with content that was sourced from a YAML file used to generate your site.

To make this work on your existing Gatsby site, you would need to:

Edit this page on GitHub