CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-gatsby-remark-prismjs

Adds syntax highlighting to code blocks at build time using PrismJS

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

gatsby-remark-prismjs

gatsby-remark-prismjs is a Gatsby remark plugin that adds syntax highlighting to code blocks in markdown files at build time using PrismJS. It transforms code blocks during the build process rather than client-side, offering extensive customization including line highlighting, line numbering, diff syntax highlighting, shell prompts, and custom language support.

Package Information

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

Core Imports

// Plugin is configured in gatsby-config.js, not imported directly
plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      plugins: [
        {
          resolve: `gatsby-remark-prismjs`,
          options: {
            // Plugin configuration options
          }
        }
      ]
    }
  }
]

Basic Usage

// gatsby-config.js
plugins: [
  {
    resolve: `gatsby-transformer-remark`,
    options: {
      plugins: [
        {
          resolve: `gatsby-remark-prismjs`,
          options: {
            classPrefix: "language-",
            inlineCodeMarker: null,
            aliases: {},
            showLineNumbers: false,
            noInlineHighlight: false,
            languageExtensions: [],
            prompt: {
              user: "root",
              host: "localhost",
              global: false,
            },
            escapeEntities: {},
          },
        },
      ],
    },
  },
]

Include a PrismJS theme in gatsby-browser.js:

// gatsby-browser.js
require("prismjs/themes/prism-solarizedlight.css")

Architecture

gatsby-remark-prismjs is built around several key components:

  • Main Plugin Function: Processes markdown AST nodes, transforming code blocks into highlighted HTML
  • Option Parser: Extracts highlighting directives and configurations from code block metadata
  • Syntax Highlighter: Core PrismJS integration with dynamic language loading
  • Directive System: Parses inline comments for line highlighting and hiding
  • Feature Modules: Specialized functionality for line numbers, command prompts, and language extensions

Capabilities

Main Plugin Function

The gatsby-remark-prismjs plugin function that processes Gatsby remark AST nodes and adds syntax highlighting.

/**
 * Main gatsby-remark-prismjs plugin function
 * @param context - Gatsby remark plugin context containing markdown AST
 * @param options - Plugin configuration options
 * @returns void - Mutates the AST in place
 */
function gatsbyRemarkPrismjs(
  context: { markdownAST: MarkdownAST },
  options?: PluginOptions
): void;

interface MarkdownAST {
  type: string;
  children: MarkdownNode[];
}

interface MarkdownNode {
  type: 'code' | 'inlineCode' | string;
  lang?: string;
  meta?: string;
  value: string;
}

Plugin Configuration

Core plugin configuration options for controlling syntax highlighting behavior, CSS classes, and feature toggles.

interface PluginOptions {
  /** CSS class prefix for code blocks (default: "language-") */
  classPrefix?: string;
  /** Separator for inline code language specification (default: null) */
  inlineCodeMarker?: string | null;
  /** Language alias mappings (default: {}) */
  aliases?: Record<string, string>;
  /** Disable inline code highlighting (default: false) */
  noInlineHighlight?: boolean;
  /** Global line numbering toggle (default: false) */
  showLineNumbers?: boolean;
  /** Show invisible characters (default: false) */
  showInvisibles?: boolean;
  /** Custom language definitions (default: []) */
  languageExtensions?: LanguageExtension[];
  /** Shell prompt configuration */
  prompt?: PromptConfig;
  /** Additional HTML entity escaping rules (default: {}) */
  escapeEntities?: Record<string, string>;
}

interface PromptConfig {
  /** Default username for shell prompts (default: "root") */
  user?: string;
  /** Default hostname for shell prompts (default: "localhost") */
  host?: string;
  /** Apply prompts globally to shell code (default: false) */
  global?: boolean;
}

Configuration

Syntax Highlighting

Core syntax highlighting functionality with support for all PrismJS languages, dynamic language loading, and diff syntax highlighting.

function highlightCode(
  language: string,
  code: string,
  additionalEscapeCharacters?: Record<string, string>,
  lineNumbersHighlight?: number[],
  noInlineHighlight?: boolean,
  diffLanguage?: string | null
): string;

Syntax Highlighting

Line Features

Advanced line-based features including line highlighting, line numbering, and line hiding capabilities controlled through code block metadata or inline directives.

function parseOptions(language: string): {
  splitLanguage?: string;
  highlightLines?: number[];
  showLineNumbersLocal?: boolean;
  numberLinesStartAt?: number;
  outputLines?: number[];
  promptUserLocal?: string;
  promptHostLocal?: string;
};

Line Features

Language Extensions

System for adding custom language definitions or extending existing PrismJS languages with custom tokens and syntax rules.

interface LanguageExtension {
  /** Name of the new language (required if not extending existing language) */
  language?: string;
  /** Language to extend (required if not creating new language) */
  extend?: string;
  /** Language definition tokens (RegExp or string patterns) */
  definition?: Record<string, RegExp | string>;
  /** Insert tokens before existing ones (requires extend or definition) */
  insertBefore?: Record<string, Record<string, RegExp | string>>;
}

/**
 * Loads custom language extensions into PrismJS
 * @param languageExtensions - Array of language extension definitions
 * @throws Error when validation fails (missing required properties)
 */
function loadLanguageExtension(languageExtensions: LanguageExtension[]): void;

Language Extensions

Shell Features

Specialized functionality for shell and bash code blocks including customizable command prompts and output line specification.

function commandLine(
  code?: string,
  highlightLines?: number[],
  user?: string,
  host?: string
): string;

Shell Features

Types

interface PluginOptions {
  /** CSS class prefix for code blocks (default: "language-") */
  classPrefix?: string;
  /** Separator for inline code language specification */
  inlineCodeMarker?: string | null;
  /** Language alias mappings */
  aliases?: Record<string, string>;
  /** Disable inline code highlighting */
  noInlineHighlight?: boolean;
  /** Global line numbering toggle */
  showLineNumbers?: boolean;
  /** Show invisible characters */
  showInvisibles?: boolean;
  /** Custom language definitions */
  languageExtensions?: LanguageExtension[];
  /** Shell prompt configuration */
  prompt?: PromptConfig;
  /** Additional HTML entity escaping rules */
  escapeEntities?: Record<string, string>;
}

interface PromptConfig {
  /** Default username for shell prompts */
  user?: string;
  /** Default hostname for shell prompts */
  host?: string;
  /** Apply prompts globally to shell code */
  global?: boolean;
}

interface LanguageExtension {
  /** Name of the new language (required if not extending existing language) */
  language?: string;
  /** Language to extend (required if not creating new language) */
  extend?: string;
  /** Language definition tokens (RegExp or string patterns) */
  definition?: Record<string, RegExp | string>;
  /** Insert tokens before existing ones (requires extend or definition) */
  insertBefore?: Record<string, Record<string, RegExp | string>>;
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/gatsby-remark-prismjs@7.15.x
Publish Source
CLI
Badge
tessl/npm-gatsby-remark-prismjs badge