gatsby-yaml-full-markdown

⚠️ Warning: the plain option will be deprecated in the future and this plugin will always return an object — the equivalent of setting plain to true. Find more info about this option here.

⚠️ Warning: see Migrating from < 4.0.0 if you are coming from older versions.

Plugin for gatsby-transformer-yaml-full to enable Markdown to HTML conversion using !markdown tag. The conversion is handled by remark.

Installation

npm install gatsby-yaml-full-markdown gatsby-transformer-yaml-full

Usage

/* gatsby-config.js */

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

Example

Note: this plugin accepts a string or a file path input; if a file is detected, the plugin will read it and return the processed data.

The following ./post.yaml and ./file.md files, respectively:

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

  Article content.
file: !markdown file.md

# Title

File content.

Will return:

{
  data: {
    postYaml: {
      title: 'Blog post',
      content: '<h2>Heading</h2>\n<p>Article content.</p>\n',
      file: '<h1>Title</h1>\n<p>File content.</p>\n'
    }
  }
}

With the following query:

query {
  postYaml {
    title
    content
    file
  }
}

Options

plain

Type: boolean. Default: false.

Returns plain text (without markups) along with HTML. When this option is enabled, the markdown node will return an object — instead of a string with HTML markup — containing two properties, html and plain.

The following ./post.yaml:

---
content: !markdown |
  ## Heading

  Article content.

Will return:

{
  data: {
    postYaml: {
      content: {
        html: '<h2>Heading</h2>\n<p>Article content.</p>\n',
        plain: 'Heading\n\nArticle content.\n'
      },
    }
  }
}

With the following query:

query {
  postYaml {
    content {
      html
      plain
    }
  }
}

remarkHtml

Type: object. Default: {}.

remark-html can be configured through remarkHtml option — i.e. if you want to allow dangerous raw HTML in the output, set the sanitize option to false. More info about remark-html options can be found here.

Migrating from < 4.0.0

Before version 4.0.0, this plugin generated a text/markdown node from the content, requiring a plugin like gatsby-transformer-remark to generate HTML data. This is no longer the case. gatsby-yaml-full-markdown now outputs processed data directly on the node, using remark-html to convert Markdown to HTML.

License

The MIT License