Skip to main content
Community Plugin
View plugin on GitHub
See starters using this

gatsby-transformer-yaml-full

YAML parser with support for custom types and multiple documents.

Install and configure

$ npm install gatsby-transformer-yaml-full

Basic configuration

// gatsby-config.js

module.exports = {
  plugins: [
    `gatsby-transformer-yaml-full`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        path: `./content`, // Path to your .yaml (or .yml) files
      },
    },
  ],
}

Note: gatsby-transformer-yaml-full requires a source plugin like gatsby-source-filesystem.

Enable custom types with plugins

You can extend the parser functionality with plugins (e.g., gatsby-yaml-full-markdown).

// gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-yaml-full`,
      options: {
        plugins: [
          `gatsby-yaml-full-markdown`, // Enable !markdown tags
        ],
      },
    },
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        path: `./content`,
      },
    },
  ],
}

Usage

You can organize your data as multiple documents in individual files or as single documents spread across multiple files:

  • Multiple Documents: each file represents a collection and each document represents a record
  • Single Document: each folder represents a collection and each file represents a record

Multiple documents

Convert each document inside a file into a node. The node type is based on the file name.

YAML file

# content/collection.yaml

character: a
number: 1

---

character: b
number: 2

---

character: c
number: 3

GraphQL query

{
  allCollectionYaml {
    edges {
      node {
        character
        number
      }
    }
  }
}

Returning object

{
  allCollectionYaml: {
    edges: [
      {
        node: {
          character: 'a',
          number: 1,
        },
      },
      {
        node: {
          character: 'b',
          number: 2,
        },
      },
      {
        node: {
          character: 'c',
          number: 3,
        },
      },
    ]
  }
}

Single Document

Convert each file inside a directory into a node. The node type is based on the directory name.

Folder structure

content/
  posts/
    blog-post.yaml
    hello-world.yaml
    new-post.yaml

YAML files

# content/posts/blog-post.yaml

title: Blog post
# content/posts/hello-world.yaml

title: Hello, world!
# content/posts/new-post.yaml

title: New post

GraphQL query

{
  allPostsYaml {
    edges {
      node {
        title
      }
    }
  }
}

Returning object

{
  allPostsYaml: {
    edges: [
      {
        node: {
          title: 'Blog post',
        },
      },
      {
        node: {
          title: 'Hello, world!',
        },
      },
      {
        node: {
          title: 'New post',
        },
      },
    ]
  }
}

Type plugins

You can extend the parser funcionality with plugins. Enabling gatsby-yaml-full-markdown plugin, the following document:

title: Blog post
content: !markdown |
  ## Heading

  Article content.

Would return:

{
  title: 'Blog post',
  content: '<h2>Heading</h2>\n<p>Article content.</p>\n',
}

Additional information

Options

  • plugins (array): sets the plugins that should be enabled by gatsby-transformer-yaml-full
  • createChildNodes (boolean): create nodes for each parent in the object tree alongside its own child elements (it’s required β€” and automatically set β€” by gatsby-yaml-full-file and possibly other plugins)

createChildNodes example

If createChildNodes is set to true, the document below:

# people.yaml

--- # Indicates a multi document file

gallery:
  items:
  - title: Gallery item
    description: 1st entry
  - title: Another gallery item
    description: Last entry

Would create the following nodes:

{
  allPeopleYaml {
    edges {
      node {
        # createChildNodes enabled tree
        childPeopleGalleryYaml {
          childPeopleGalleryItemsYaml {
            title
            description
          }
        }
        # Regular tree
        gallery {
          items {
            title
            description
          }
        }
      }
    }
  }
}

Writing plugins

The plugin should return a function, which should return an object with the following properties:

The first argument of the function will be the same object received from Gatsby on exports.onCreateNode. The second will be the plugin options object set in gatsby-config.js.

// index.js

module.exports = function ({ node }, pluginOptions) {
  return {
    tag: '!example',
    options: {
      kind: 'scalar',
      construct: () => `Parent directory is ${node.dir}`,
    },
  }
}