or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-gatsby-remark-smartypants

Gatsby remark plugin that enhances typography by replacing dumb punctuation marks with smart punctuation marks

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/gatsby-remark-smartypants@6.15.x

To install, run

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

gatsby-remark-smartypants

gatsby-remark-smartypants is a Gatsby remark plugin that automatically enhances typography in markdown content by replacing "dumb" punctuation marks with "smart" punctuation marks using the retext-smartypants library.

Package Information

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

Core Imports

// CommonJS (typically used in gatsby-config.js)
const gatsbyRemarkSmartypants = require("gatsby-remark-smartypants");

For TypeScript projects:

import gatsbyRemarkSmartypants from "gatsby-remark-smartypants";

Note: This plugin is typically not imported directly in user code but configured as part of gatsby-transformer-remark's plugin chain in gatsby-config.js.

Basic Usage

// In gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          `gatsby-remark-smartypants`
        ],
      },
    },
  ],
}

With custom options:

// In gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          {
            resolve: `gatsby-remark-smartypants`,
            options: {
              dashes: "oldschool",
              quotes: true,
              ellipses: true,
              backticks: true
            }
          }
        ],
      },
    },
  ],
}

For TypeScript projects (gatsby-config.ts):

import type { GatsbyConfig } from "gatsby";

const config: GatsbyConfig = {
  plugins: [
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          {
            resolve: `gatsby-remark-smartypants`,
            options: {
              dashes: "oldschool",
              quotes: true,
              ellipses: true,
              backticks: true
            }
          }
        ],
      },
    },
  ],
};

export default config;

Capabilities

Plugin Function

The main plugin function processes markdown AST nodes to enhance typography.

/**
 * Gatsby remark plugin function that enhances typography in markdown content
 * @param {Object} params - Plugin parameters containing markdownAST
 * @param {Object} params.markdownAST - The markdown Abstract Syntax Tree to process
 * @param {Object} [pluginOptions={}] - Configuration options passed to retext-smartypants
 * @returns {Object} The processed markdown AST with enhanced typography
 */
function gatsbyRemarkSmartypants({ markdownAST }, pluginOptions = {}) {
  // Implementation processes all text nodes in the AST
  // using retext-smartypants with the provided options
  return markdownAST;
}

Configuration Options

All options are passed through to retext-smartypants. The following options are available:

interface SmartypantsOptions {
  /** Whether to transform straight quotes to smart quotes (default: true) */
  quotes?: boolean;
  
  /** 
   * Dash transformation behavior (default: true)
   * - true: Two dashes become em dash
   * - "oldschool": Three dashes become em dash, two dashes become en dash  
   * - "inverted": Three dashes become en dash, two dashes become em dash
   * - false: No dash transformation
   */
  dashes?: boolean | 'oldschool' | 'inverted';
  
  /** 
   * Ellipsis transformation behavior (default: true)
   * - true: Transform triple dots with or without spaces
   * - "spaced": Transform triple dots with spaces only
   * - "unspaced": Transform triple dots without spaces only
   * - false: No ellipsis transformation
   */
  ellipses?: boolean | 'spaced' | 'unspaced';
  
  /** Backtick quote transformation behavior (default: true) */
  backticks?: boolean | 'all';
  
  /** Custom opening quote characters */
  openingQuotes?: {
    double: string;
    single: string;
  };
  
  /** Custom closing quote characters */
  closingQuotes?: {
    double: string;
    single: string;
  };
}

Usage Examples

Default Configuration

// gatsby-config.js
{
  resolve: `gatsby-remark-smartypants`,
  // Uses default options: all transformations enabled
}

Transforms:

"Hello" → "Hello"
'Hello' → 'Hello'
He said, "A 'simple' sentence..." → He said, "A 'simple' sentence…"
-- → — (em dash)
... → … (ellipsis)

Custom Dash Behavior

// gatsby-config.js
{
  resolve: `gatsby-remark-smartypants`,
  options: {
    dashes: "oldschool"
  }
}

Transforms:

--- → — (em dash)
-- → – (en dash)

Selective Options

// gatsby-config.js
{
  resolve: `gatsby-remark-smartypants`,
  options: {
    quotes: true,
    dashes: false,
    ellipses: "unspaced",
    backticks: "all"
  }
}

Only transforms quotes, ellipses without spaces, and all backtick patterns.

Custom Quote Characters

// gatsby-config.js
{
  resolve: `gatsby-remark-smartypants`,
  options: {
    openingQuotes: {
      double: "«",
      single: "‹"
    },
    closingQuotes: {
      double: "»", 
      single: "›"
    }
  }
}

Uses custom French-style quotation marks.

Types

interface PluginParams {
  /** The markdown Abstract Syntax Tree to process */
  markdownAST: object;
}

interface MarkdownAST {
  /** Node type identifier */
  type: string;
  /** Node value for text nodes */
  value?: string;
  /** Child nodes */
  children?: MarkdownAST[];
}

Dependencies

retext: ^7.0.1 - Text processing framework
retext-smartypants: ^4.0.0 - Core smartypants typography enhancement
unist-util-visit: ^2.0.3 - Utility for traversing unist syntax trees

Peer Dependencies

gatsby: ^5.0.0-next - Required for Gatsby integration

Error Handling

The plugin is designed to be robust and will skip processing if:

The markdownAST parameter is not provided
Text nodes cannot be processed by retext-smartypants
Invalid options are provided (they are passed through to retext-smartypants)

No explicit error handling is required in configuration.

Node.js Compatibility

Minimum Node.js version: 18.0.0