tessl/npm-gatsby-transformer-remark

Gatsby transformer plugin for Markdown using the Remark library and ecosystem

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Markdown Node Creation

Name: tessl/npm-gatsby-transformer-remark
Author: tessl

Core functionality for creating MarkdownRemark GraphQL nodes from Markdown files, with frontmatter parsing and parent-child relationship management.

Capabilities

Node Creation Function

Main function that processes File nodes with markdown media types and creates corresponding MarkdownRemark nodes.

/**
 * Creates MarkdownRemark nodes from markdown File nodes
 * @param nodeApiArgs - Gatsby node creation context
 * @param nodeApiArgs.node - The File node to process
 * @param nodeApiArgs.loadNodeContent - Function to load file content
 * @param nodeApiArgs.actions - Gatsby actions including createNode and createParentChildLink
 * @param nodeApiArgs.createNodeId - Function to create unique node IDs
 * @param nodeApiArgs.reporter - Gatsby reporter for logging
 * @param nodeApiArgs.createContentDigest - Function to create content digests
 * @param pluginOptions - Plugin configuration options
 * @returns Promise resolving to created MarkdownRemark node
 */
async function onCreateNode(
  {
    node,
    loadNodeContent,
    actions,
    createNodeId,
    reporter,
    createContentDigest,
  },
  pluginOptions
): Promise<MarkdownRemark>;

Usage Example:

This function is automatically called by Gatsby when processing File nodes. The created MarkdownRemark node includes:

const markdownNode = {
  id: createNodeId(`${node.id} >>> MarkdownRemark`),
  children: [],
  parent: node.id,
  internal: {
    content: data.content, // Markdown content without frontmatter
    type: `MarkdownRemark`,
    contentDigest: contentDigest,
  },
  frontmatter: {
    title: ``, // Default title, overridden by frontmatter
    ...data.data, // Parsed frontmatter data
  },
  excerpt: data.excerpt, // From gray-matter if excerpt_separator used
  rawMarkdownBody: data.content, // Original markdown content
  fileAbsolutePath: node.absolutePath, // If parent is File node
};

Node Filtering Function

Determines whether a File node should be processed by this plugin based on media type.

/**
 * Determines if a node should be processed by the transformer
 * @param params - Object containing the node to check
 * @param params.node - The Gatsby node to evaluate
 * @returns true if node should be processed (has markdown media type)
 */
function shouldOnCreateNode({ node }): boolean;

Supported Media Types:

text/markdown
text/x-markdown

Usage Example:

// This function is automatically called by Gatsby
const shouldProcess = shouldOnCreateNode({
  node: {
    internal: {
      mediaType: "text/markdown" // Will return true
    }
  }
});

Frontmatter Processing

The plugin uses gray-matter to parse frontmatter with the following processing:

Data Type Conversion

// Date objects are converted to JSON strings
if (_.isDate(value)) {
  return value.toJSON();
}

Security Considerations

The plugin includes security measures for JavaScript frontmatter:

Default: JS frontmatter engines are disabled and stubbed
Warning: Shows security warnings when JS frontmatter is detected
Option: Can be enabled via jsFrontmatterEngine: true (not recommended)

Supported Frontmatter Formats

YAML (default): Standard frontmatter format
JSON: Using ---json delimiter
TOML: Using ---toml delimiter
JavaScript: Using ---js or ---javascript (disabled by default for security)

Example Markdown with Frontmatter:

---
title: "My Blog Post"
date: "2023-12-01"
tags: ["gatsby", "markdown"]
published: true
---

# My Blog Post

This is the content of my blog post.

Error Handling

The plugin provides comprehensive error handling during node creation:

try {
  // Node creation logic
} catch (err) {
  reporter.panicOnBuild(
    `Error processing Markdown ${
      node.absolutePath ? `file ${node.absolutePath}` : `in node ${node.id}`
    }:\n
    ${err.message}`
  );
  return {}; // Return empty object on error
}

Common error scenarios: