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

$ npm install gatsby-transformer-yaml-full

Configure

Using with gatsby-source-filesystem

// 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',
      },
    },
  ],
}

Options

plugins

Default: []. Type: Array.

Enable specific YAML types (e.g. gatsby-yaml-full-import or gatsby-yaml-full-markdown)

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

# 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.

Directory structure

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

YAML files

# posts/blog-post.yaml

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

title: Hello, world!
# 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',
}

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 helpers 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}`,
    },
  }
}

More information about creating local plugins, specific to your project, can be found on Gatsby documentation.