Plugin Configuration

/**
 * Defines plugin options schema for validation
 * @param context - Plugin schema context
 * @param context.Joi - Joi validation library instance
 * @returns Joi schema object for plugin options validation
 */
function pluginOptionsSchema({ Joi }): Joi.Schema;

/**
 * Activates Footnotes mode
 * @default true
 */
footnotes: boolean;

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        footnotes: true, // Enable footnotes processing
      },
    },
  ],
}

Here is a footnote reference[^1].

[^1]: This is the footnote content.

/**
 * Activates GitHub Flavored Markdown mode
 * @default true
 */
gfm: boolean;

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        gfm: true, // Enable GitHub Flavored Markdown
      },
    },
  ],
}

/**
 * HTML tag to use as excerpt separator
 * If your Markdown file contains HTML, excerpt will not return a value unless this is set
 */
excerpt_separator?: string;

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        excerpt_separator: `<!-- endexcerpt -->`,
      },
    },
  ],
}

---
title: "My Post"
---

This content will be included in the excerpt.

<!-- endexcerpt -->

This content will NOT be included in the excerpt.

/**
 * List of remark plugins with their configurations
 * See: https://github.com/gatsbyjs/gatsby/tree/master/examples/using-remark
 */
plugins: Array<PluginConfig>;

interface PluginConfig {
  resolve: string;
  options?: Record<string, any>;
}

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          // Simple plugin without options
          `gatsby-remark-copy-linked-files`,
          // Plugin with configuration
          {
            resolve: `gatsby-remark-images`,
            options: {
              maxWidth: 756,
              quality: 90,
            },
          },
          // Plugin with complex configuration
          {
            resolve: `gatsby-remark-prismjs`,
            options: {
              classPrefix: "language-",
              inlineCodeMarker: null,
              showLineNumbers: true,
            },
          },
        ],
      },
    },
  ],
}

/**
 * Enable JS for gray-matter frontmatter parsing
 * @default false
 * @security This can cause security risks - use with caution
 */
jsFrontmatterEngine: boolean;

// gatsby-config.js - NOT RECOMMENDED
module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        jsFrontmatterEngine: true, // Security risk - avoid unless necessary
      },
    },
  ],
}

---js
{
  title: "Generated Title",
  date: new Date().toISOString(),
  tags: ["tag1", "tag2"].map(tag => tag.toUpperCase())
}
---

# Content here

/**
 * Custom block types for remark parsing
 */
blocks?: string[];

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        blocks: ["custom-block"], // Custom block types
      },
    },
  ],
}

/**
 * Default options for table of contents generation
 */
tableOfContents?: {
  /**
   * Start ToC from this heading onwards
   * @default null
   */
  heading?: string | null;
  /**
   * Maximum depth of headings to include
   * @default 6
   */
  maxDepth?: number;
};

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        tableOfContents: {
          heading: "Contents", // Skip headings until "Contents" is found
          maxDepth: 3, // Only include h1, h2, h3
        },
      },
    },
  ],
}

/**
 * Custom validation that warns about JavaScript frontmatter security risks
 * and provides fallback stubs for JS/JavaScript engines when disabled
 */
.custom(value => {
  const { jsFrontmatterEngine, engines = {} } = value || {};
  
  if (jsFrontmatterEngine) {
    // Show security warning
    console.warn("JS frontmatter engine security warning...");
    return value;
  }
  
  // Provide stub engines to prevent execution
  const js = () => {
    console.warn("JS frontmatter detected but disabled for security...");
    return {}; // Return empty frontmatter
  };
  
  return {
    ...value,
    engines: {
      ...engines,
      js,
      javascript: js,
    },
  };
});

// gatsby-config.js - Complete configuration example
module.exports = {
  plugins: [
    `gatsby-source-filesystem`, // Required for file processing
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        // Remark processing options
        footnotes: true,
        gfm: true,
        excerpt_separator: `<!-- endexcerpt -->`,
        
        // Custom block types (advanced usage)
        blocks: [],
        
        // Security option (keep disabled)
        jsFrontmatterEngine: false,
        
        // Table of contents defaults
        tableOfContents: {
          heading: null,
          maxDepth: 6,
        },
        
        // Sub-plugin ecosystem
        plugins: [
          // File handling
          `gatsby-remark-copy-linked-files`,
          
          // Image processing  
          {
            resolve: `gatsby-remark-images`,
            options: {
              maxWidth: 1200,
              quality: 90,
              withWebp: true,
            },
          },
          
          // Syntax highlighting
          {
            resolve: `gatsby-remark-prismjs`,
            options: {
              classPrefix: "language-",
              inlineCodeMarker: null,
              showLineNumbers: true,
              noInlineHighlight: false,
            },
          },
          
          // External links
          {
            resolve: `gatsby-remark-external-links`,
            options: {
              target: "_blank",
              rel: "noopener noreferrer",
            },
          },
        ],
      },
    },
  ],
}