No Painful Merges

    gatsby-transformer-yaml

    5.2.0 • Public • Published

    gatsby-transformer-yaml

    Parses YAML files. Supports arrays of objects and single objects.

    Supported extensions: .yaml, .yml

    Both .yaml and .yml are treated in the same way. This document uses both of them interchangeably.

    Install

    npm install gatsby-transformer-yaml

    Note: You also need to have gatsby-source-filesystem installed and configured so it points to your files.

    How to use

    In your gatsby-config.js

    module.exports = {
      plugins: [
        `gatsby-transformer-yaml`,
        {
          resolve: `gatsby-source-filesystem`,
          options: {
            path: `./src/data/`,
          },
        },
      ],
    }

    Where the source folder ./src/data/ contains the .yaml files.

    Parsing algorithm

    You can choose to structure your data as arrays of objects in individual files or as single objects spread across multiple files.

    The source folder can contain either the following:

    • Array of Objects: Where each file represents a collection. (you probably want this one)
    • Single Object: Where each subfolder represents a collection; each file represents one "record".

    Array of Objects

    The algorithm for YAML arrays is to convert each item in the array into a node. The type of the node is based on the filename.

    So if your project has a letters.yaml which looks like:

    - character: a
    - character: b
    - character: c

    Then the following three nodes would be created.

    [
      {
        "character": "a"
      },
      {
        "character": "b"
      },
      {
        "character": "c"
      }
    ]

    Single Object

    The algorithm for single YAML objects is to convert the object defined at the root of the file into a node. The type of the node is based on the name of the parent directory.

    For example, let's say your project has a data layout like:

    data/
        letters/
            a.yml
            b.yml
            c.yml
    

    Where each of a.yml, b.yml and c.yml look like:

    character: a
    character: b
    character: c

    Then the following three nodes would be created.

    [
      {
        "character": "a"
      },
      {
        "character": "b"
      },
      {
        "character": "c"
      }
    ]

    How to query

    You can query the nodes using GraphQL, like from the GraphiQL browser: http://localhost:8000/___graphql.

    Regardless of whether you choose to structure your data in arrays of objects or single objects, you'd be able to query your letters like:

    {
      allLettersYaml {
        edges {
          node {
            character
          }
        }
      }
    }

    Which would return:

    {
      allLettersYaml: {
        edges: [
          {
            node: {
              character: "a",
            },
          },
          {
            node: {
              character: "b",
            },
          },
          {
            node: {
              character: "c",
            },
          },
        ]
      }
    }

    Please do note that allLettersYaml will not show up if you do not have any .yaml files.

    Configuration options

    typeName [string|function][optional]

    The default naming convention documented above can be changed with either a static string value (e.g. to be able to query all yaml with a simple query):

    module.exports = {
      plugins: [
        {
          resolve: `gatsby-transformer-yaml`,
          options: {
            typeName: `Yaml`, // a fixed string
          },
        },
      ],
    }
    {
      allYaml {
        edges {
          node {
            value
          }
        }
      }
    }

    or a function that receives the following arguments:

    • node: the graphql node that is being processed, e.g. a File node with yaml content
    • object: a single object (either an item from an array or the whole yaml content)
    • isArray: boolean, true if object is part of an array
    - level: info
      message: hurray
    - level: info
      message: it works
    - level: warning
      message: look out
    module.exports = {
      plugins: [
        {
          resolve: `gatsby-transformer-yaml`,
          options: {
            typeName: ({ node, object, isArray }) => object.level,
          },
        },
      ],
    }
    {
      allInfo {
        edges {
          node {
            message
          }
        }
      }
    }

    Troubleshooting

    id and yamlId key

    If your data contains an id key the transformer will automatically convert this key to yamlId as id is a reserved internal keyword for Gatsby.

    Install

    npm i gatsby-transformer-yaml

    DownloadsWeekly Downloads

    10,723

    Version

    5.2.0

    License

    MIT

    Unpacked Size

    41.4 kB

    Total Files

    7

    Last publish

    Collaborators

    • kathmbeck
    • j0sh77
    • tyhopp
    • kgarbaya
    • marvinjudehk
    • dschau
    • kylemathews
    • pieh
    • wardpeet
    • tylerbarnes
    • fk
    • smthomas
    • lekoarts
    • rachelbahl
    • daniellewgatsby
    • abhiaiyer