gatsby-plugin-json-remark

gatsby-plugin-json-remark is a GatsbyJs plugin that transforms markdown content from JSON files. The new MarkdownRemark nodes are placed inside the original gatsby-transformer-json node tree. Transformed HTML is also populated in new node properties as the original JSON key names appended with “Html”.

This plugin piggybacks off of the existing gatsby-transformer-remark plugin configuration in gatsby-config.json and honors all additional parsing provided by its sub-plugins (e.g. gatsby-remark-prismjs). This is accomplished on the *Html fields by retrieving the HTML from the MarkdownRemark nodes’ own html resolvers.

The ability to place markdown in structured JSON files comes in handy for CMS software that stores its content inside JSON files. In TinaCMS for example, gatsby-plugin-json-remark can be used to embed markdown in the structured page content using TinaCMS’ markdown blocks feature.

Please create an issue for question, bug, idea, etc. If this plugin doesn’t fit your particular use case but you feel that it should, please open an issue to request the new feature. PRs welcome 👍.

Note: It is recommended to use gatsby-remark-remove-root-p-tag in tandem with this plugin. gatsby-transformer-remark will often automatically wrap a paragraph node around markdown snippets, resulting in an unintended <p> tag wrapping the transformed HTML. gatsby-remark-remove-root-p-tag will remove the paragraph parent from the markdown AST.

Install

Add gatsby-plugin-json-remark package to your gatsby project:

npm

npm i gatsby-plugin-json-remark

yarn

yarn add gatsby-plugin-json-remark

Configure

Add plugin to the gatsby-plugin-json-remark plugins array in your gatsby-config.js:

module.exports = {
  plugins: [
    // ...
    {
      resolve: `gatsby-plugin-json-remark`,
      options: {
        paths: [
          `${__dirname}/content/pages`,
          `${__dirname}/content/json-markdown`,
        ], // Process all JSON files in these directories.
        pathsExclude: [`${__dirname}/content/pages/contact.json`], // Process all files in the directories above, except `pages/contact.json`.
        fieldNameBlacklist: [
          "id",
          "children",
          "parent",
          "fields",
          "internal",
          "path",
          "template",
        ],
      },
    },
    // ...
  ],
};

Optional: add gatsby-remark-remove-root-p-tag as a sub-plugin to `gatsby-transformer-remark’ to remove unwanted HTML paragraph tags from the generaged HTML.

module.exports = {
  plugins: [
    // ...
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          {
            resolve: `gatsby-remark-remove-root-p-tag`,
            options: {
              parents: ["gatsby-plugin-json-remark", "default-site-plugin"], // Required: will process only the MarkdownRemark nodes created by these plugins
            },
          },
        ],
      },
    },
    // ...
  ],
};

Options

paths (required)

Values can be JSON file paths or directory paths. The plugin will only process these files and directories. Note: see requirements below.

pathsExclude (optional)

Values can be JSON file paths or directory paths which serve as exceptions to the paths option. The plugin will ignore the files and directories provided here, even if they are configured with the paths option. This option is handy when a directory is configured with the paths option but certain files in that directory should be ignored.

fieldNameBlacklist (optional / recommended)

A list of JSON keys that will be ignored in the source JSON files. This is useful for preventing conflicts with the reserved property names of the Gatsby node data structure.

Requirements

gatsby-config.js Dependencies

• gatsby-transformer-remark
• gatsby-source-filesystem Configured with at least one directory containing JSON files. The paths option of gatsby-plugin-json-remark must contain at least a directory or a file that is also configured with gatsby-source-filesystem. Otherwise, there will be no JSON nodes to process.

Environment

• Node >=12.16.1
• Gatsby v2