or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

field-extensions.mdindex.mdnode-creation.mdplugin-configuration.mdschema-customization.md
tile.json

tessl/npm-gatsby-transformer-remark

Gatsby transformer plugin for Markdown using the Remark library and ecosystem

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/gatsby-transformer-remark@6.15.x

To install, run

npx @tessl/cli install tessl/npm-gatsby-transformer-remark@6.15.0

index.mddocs/

gatsby-transformer-remark

gatsby-transformer-remark is a Gatsby transformer plugin that parses Markdown files using the Remark library and ecosystem. It transforms Markdown files with frontmatter into GraphQL-queryable MarkdownRemark nodes, providing rich functionality including HTML rendering, table of contents generation, excerpt creation, heading extraction, and support for the broader gatsby-remark-* plugin ecosystem.

Package Information

  • Package Name: gatsby-transformer-remark
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install gatsby-transformer-remark

Core Imports

As a Gatsby plugin, gatsby-transformer-remark is configured in your gatsby-config.js:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        // Plugin options
      },
    },
  ],
}

Basic Usage

// gatsby-config.js
module.exports = {
  plugins: [
    `gatsby-source-filesystem`, // Required for file processing
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        footnotes: true,
        gfm: true,
        plugins: [], // Add gatsby-remark-* plugins here
      },
    },
  ],
}

Query MarkdownRemark nodes in GraphQL:

{
  allMarkdownRemark {
    edges {
      node {
        html
        frontmatter {
          title
        }
        excerpt
        headings {
          depth
          value
        }
        timeToRead
        tableOfContents
      }
    }
  }
}

Architecture

gatsby-transformer-remark integrates deeply with Gatsby's GraphQL data layer and plugin ecosystem:

  • Node Creation: Transforms File nodes with markdown media types into MarkdownRemark nodes
  • GraphQL Schema Extension: Adds rich fields like html, excerpt, headings, and timeToRead to MarkdownRemark type
  • Plugin Ecosystem: Integrates with gatsby-remark-* sub-plugins for extended Markdown processing
  • Caching System: Provides sophisticated caching for AST, HTML, and computed fields to optimize builds
  • Frontmatter Processing: Uses gray-matter for parsing YAML/JSON frontmatter with security considerations

Capabilities

Markdown Node Creation

Creates MarkdownRemark GraphQL nodes from Markdown files, parsing frontmatter and setting up parent-child relationships with File nodes.

// Gatsby Node API functions
exports.onCreateNode = async function onCreateNode(nodeApiArgs, pluginOptions): Promise<MarkdownRemark>;
exports.shouldOnCreateNode = function shouldOnCreateNode({ node }): boolean;

Node Creation

GraphQL Schema Customization

Defines comprehensive GraphQL types for MarkdownRemark including heading, excerpt format, and word count types.

exports.createSchemaCustomization = function createSchemaCustomization(nodeApiArgs, pluginOptions): void;

// GraphQL Types
type MarkdownRemark {
  html: String
  htmlAst: JSON
  excerpt(pruneLength: Int, truncate: Boolean, format: MarkdownExcerptFormats): String
  excerptAst(pruneLength: Int, truncate: Boolean): JSON
  headings(depth: MarkdownHeadingLevels): [MarkdownHeading]
  timeToRead: Int
  tableOfContents(absolute: Boolean, pathToSlugField: String, maxDepth: Int, heading: String): String
  wordCount: MarkdownWordCount
}

Schema Customization

GraphQL Field Extensions

Extends MarkdownRemark with computed fields for HTML rendering, excerpts, headings extraction, and more.

exports.setFieldsOnGraphQLNodeType = function setFieldsOnGraphQLNodeType(context, pluginOptions): Promise<Object>;

Field Extensions

Plugin Configuration

Comprehensive plugin options schema with validation for footnotes, GitHub Flavored Markdown, sub-plugins, and frontmatter processing.

exports.pluginOptionsSchema = function pluginOptionsSchema({ Joi }): Joi.Schema;

interface PluginOptions {
  footnotes?: boolean;
  gfm?: boolean;
  excerpt_separator?: string;
  plugins?: Array<PluginConfig>;
  jsFrontmatterEngine?: boolean;
  blocks?: string[];
  tableOfContents?: {
    heading?: string;
    maxDepth?: number;
  };
}

Plugin Configuration

Types

interface MarkdownRemark {
  id: string;
  frontmatter: Record<string, any>;
  excerpt: string;
  rawMarkdownBody: string;
  fileAbsolutePath?: string;
}

interface MarkdownHeading {
  id: string | null;
  value: string;
  depth: number;
}

interface MarkdownWordCount {
  paragraphs: number;
  sentences: number;
  words: number;
}

enum MarkdownExcerptFormats {
  PLAIN = "PLAIN",
  HTML = "HTML", 
  MARKDOWN = "MARKDOWN"
}

enum MarkdownHeadingLevels {
  h1 = "h1",
  h2 = "h2", 
  h3 = "h3",
  h4 = "h4",
  h5 = "h5",
  h6 = "h6"
}