or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

field-extensions.md index.md node-creation.md plugin-configuration.md schema-customization.md

tile.json

Markdown Node Creation

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:

Invalid frontmatter syntax: YAML/JSON parsing errors
File read errors: Unable to load file content
Content digest creation errors: Node processing failures