gatsby-transformer-yaml-fulls
v1.0.0
Published
YAML parser with support for custom tags and multiple document sources
Downloads
5
Maintainers
Readme
gatsby-transformer-yaml-full
This it's a fork of gatsby-transformer-yaml-full
YAML parser with support for custom tags and multiple document sources.
Installation
npm install gatsby-transformer-yaml-full
Usage
Note:
gatsby-transformer-yaml-full
requires a source plugin.
/* gatsby-config.js */
module.exports = {
plugins: [
'gatsby-transformer-yaml-full',
{
resolve: 'gatsby-source-filesystem',
options: {
// 'name' allows users to specify a custom name for the data set.
// In this case, 'cars' becomes the name of the created data set.
name: 'cars',
// 'path' specifies the location of the data files.
path: path.join(__dirname, 'content', 'cars',),
}
}
]
}
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 ./collection.yaml
file below:
---
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:
/* gatsby-config.js */
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'
}
Options
plugins
Type: Array
. Default: []
.
Enable custom YAML tags (e.g. gatsby-yaml-full-import
,
gatsby-yaml-full-markdown
, etc.).
id
and yamlId
To keep consistency with the official gatsby-transformer-yaml
plugin, if a
YAML file contains an id
field, it'll be renamed to yamlId
— id
is a
reserved key in Gatsby.
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.