gatsby-transformer-yaml-full

YAML parser with support for custom tags and multiple document sources.

Install

$ npm install gatsby-transformer-yaml-full

Enable the plugin in gatsby-config.js:

module.exports = {
  plugins: [
    'gatsby-transformer-yaml-full',
    // {
    //   resolve: 'gatsby-source-filesystem',
    //   options: {
    //     path: './content', // Folder containing YAML files
    //   }
    // }
  ]
}

Note: gatsby-transformer-yaml-full requires a source plugin, like gatsby-source-filesystem in the example above.

Usage

You can organize your data as multiple documents, with all documents inside a single file, or as single documents, with a single document per file:

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

— The following ./collection.yaml file:

---
character: a
number: 1

---
character: b
number: 2

— Will return:

{
  data: {
    allCollectionYaml: {
      nodes: [
        {
          character: 'a',
          number: 1
        },
        {
          character: 'b',
          number: 2
        }
      ]
    }
  }
}

— With the following query:

query {
  allCollectionYaml {
    nodes
      character
      number
    }
  }
}

Single document

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

— The following directory structure:

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

— With ./posts/blog-post.yaml and ./posts/hello-world.yaml files, respectively:

title: Blog post

title: Hello, world!

— Will return:

{
  data: {
    allCollectionYaml: {
      nodes: [
        {
          title: 'Blog post'
        },
        {
          title: 'Hello, world!'
        }
      ]
    }
  }
}

— With the following query:

query {
  allPostsYaml {
    nodes
      title
    }
  }
}

Enable custom tags with plugins

With plugins, specific YAML tags can be enabled and processed.

Example

— With gatsby-yaml-full-markdown plugin activated:

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-transformer-yaml-full',
      options: {
        plugins: ['gatsby-yaml-full-markdown']
      }
    }
    // ...
  ]
}

— Using a !markdown tag:

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

  Article content.

— Will return:

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

Configure

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-transformer-yaml-full',
      // options: {
      //   plugins: [
      //     // ...gatsby-transformer-yaml-full plugins
      //   ]
      // }
    }
    // ...
  ]
}

plugins

Type: Array. Default: [].

Enable custom YAML tags (e.g. gatsby-yaml-full-import, gatsby-yaml-full-markdown, etc.).

Writing plugins

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

• tag (string): the tag of the new type (e.g. !import, !markdown)
• options: passed to JS-YAML Type constructor

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.

License

The MIT License