Registry / web-framework / gatsby-remark-prismjs

gatsby-remark-prismjs

library7.16.0jsnpmunverified

gatsby-remark-prismjs is a Gatsby plugin designed to add syntax highlighting to code blocks within Markdown files during the build process, leveraging the popular PrismJS library. It is currently at version 7.16.0 and is a core component of the Gatsby ecosystem, with its release and maintenance closely aligned with Gatsby's own development cycle. As an official Gatsby plugin, it is actively maintained. Its primary differentiator is performing syntax highlighting at build time, pre-rendering the highlighted code into static HTML. This approach eliminates the need for client-side JavaScript to process and highlight code, leading to improved perceived performance and a faster initial page load compared to client-side highlighting solutions. It offers extensive configuration for themes, line numbering, language aliases, and custom language definitions.

web-framework

npm install gatsby-remark-prismjs

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GATSBY-REMARK-PRIS

gatsby-remark-prismjs

web-frameworkjavascriptv7.16.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PrismJS Theme CSS

✓ require("prismjs/themes/prism-okaidia.css")

✗ import "prismjs/themes/prism-okaidia.css"

Themes are CSS files; they should be imported/required in `gatsby-browser.js`. CommonJS `require` is typical for Gatsby's build process. Choose one of the many available themes.

PrismJS Plugin CSS (e.g., Line Numbers)

✓ require("prismjs/plugins/line-numbers/prism-line-numbers.css")

✗ import "prismjs/plugins/line-numbers/prism-line-numbers.css"

Optional PrismJS plugin CSS files (like for line numbers or command line prompts) must also be explicitly required in `gatsby-browser.js` to apply their styles.

Prism (for custom language definitions)

✓ import Prism from 'prismjs'

✗ import { Prism } from 'prismjs'

While `gatsby-remark-prismjs` handles many language extensions via options, advanced customization or registering entirely new languages might require importing the `Prism` object directly from the `prismjs` package to interact with its API.

This quickstart demonstrates the core setup for `gatsby-remark-prismjs` in `gatsby-config.js` as a child plugin of `gatsby-transformer-remark`. It includes options for line numbers, language aliases, and a custom language extension. It also shows the necessary CSS theme and plugin imports in `gatsby-browser.js` and provides example Markdown code blocks for testing.

/* In gatsby-config.js */ module.exports = { plugins: [ { resolve: `gatsby-source-filesystem`, options: { name: `blog`, path: `${__dirname}/content/blog`, }, }, { resolve: `gatsby-transformer-remark`, options: { plugins: [ { resolve: `gatsby-remark-prismjs`, options: { classPrefix: "language-", showLineNumbers: true, aliases: { js: "javascript", sh: "bash" }, languageExtensions: [ { language: "customjs", extend: "javascript", definition: { custom_keyword: /(customKeyword)/, }, }, ], }, }, ], }, }, ], } /* In gatsby-browser.js */ require("prismjs/themes/prism-tomorrow.css") require("prismjs/plugins/line-numbers/prism-line-numbers.css") /* Example Markdown File (e.g., content/blog/my-post.md) */ ```js // JavaScript Example const greeting = "Hello, Gatsby!"; console.log(greeting); ``` ```customjs // Custom JavaScript with customKeyword function customFunction() { customKeyword console.log("This is a custom highlight."); } customFunction(); ``` ```bash {numberLines: true} # Shell Example with line numbers echo "Hello from Bash" npm install ```

Debug

Known issues

breaking`gatsby-remark-prismjs` requires Gatsby v5.0.0-next or newer, as specified by its peer dependencies. Ensure your Gatsby installation meets this requirement to avoid compatibility issues. Gatsby v5 also requires Node.js >=18.0.0.

fix

Upgrade Gatsby to `^5.0.0` or higher, and ensure your Node.js version is `^18.0.0` or higher. For example, `npm install gatsby@latest`.

affects: <7.0.0

gotchaThis plugin operates as a child plugin of `gatsby-transformer-remark`. If `gatsby-transformer-remark` is not installed and configured in your `gatsby-config.js`, `gatsby-remark-prismjs` will not function, and Markdown files will not be processed for highlighting.

fix

Ensure `gatsby-transformer-remark` is installed (`npm install gatsby-transformer-remark`) and correctly configured in your `gatsby-config.js` with `gatsby-remark-prismjs` nested within its `plugins` array.

affects: >=1.0.0

gotchaSyntax highlighting styles will not appear unless you explicitly import a PrismJS theme CSS file (e.g., `prism-tomorrow.css`) in your `gatsby-browser.js` file. This is a common oversight that leads to unstyled code blocks.

fix

Add `require("prismjs/themes/<your-chosen-theme>.css")` to your `gatsby-browser.js`. Replace `<your-chosen-theme>` with a valid PrismJS theme name.

affects: >=1.0.0

gotchaIf you are using MDX, `gatsby-remark-prismjs` is typically not compatible with `gatsby-plugin-mdx` for processing code blocks, as it's designed for `gatsby-transformer-remark`. For MDX, you often need to use solutions like `prism-react-renderer` or a custom component to handle highlighting.

fix

For MDX projects, consider using client-side highlighting with `prism-react-renderer` or ensure a custom MDX component is set up to render code blocks with PrismJS, rather than relying on `gatsby-remark-prismjs`.

affects: >=1.0.0

gotchaOrder of plugins within `gatsby-transformer-remark`'s `plugins` array matters. If you have multiple remark plugins that modify code blocks (e.g., `gatsby-remark-codefence`), the plugin listed first will take precedence for a given code block.

fix

Arrange your remark plugins in `gatsby-config.js` in the desired processing order. Place `gatsby-remark-prismjs` after any plugins that might extract or transform code blocks before highlighting is applied.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'gatsby-transformer-remark'

`gatsby-transformer-remark` is a required peer dependency and parent plugin for `gatsby-remark-prismjs` but is not installed or incorrectly referenced.

fix

Install `gatsby-transformer-remark` by running `npm install gatsby-transformer-remark` or `yarn add gatsby-transformer-remark`.

Code blocks not highlighted / No syntax highlighting appears.

The required PrismJS CSS theme file has not been imported in `gatsby-browser.js`, or the language specified in the Markdown code block is not recognized by PrismJS.

fix

Ensure `require("prismjs/themes/<your-theme>.css")` is present in `gatsby-browser.js`. Verify the language specified in your Markdown code block (e.g., ````javascript````) is a supported PrismJS language or an alias configured in the plugin options. Check for any conflicting client-side PrismJS initialization.

error glob@11.0.3: The engine "node" is incompatible with this module. Expected version "20 || >=22". Got "18.6.0"

Your Node.js version is incompatible with Gatsby or one of its dependencies. Gatsby v5 and its ecosystem plugins like `gatsby-remark-prismjs` increasingly require newer Node.js versions.

fix

Update your Node.js environment to a version compatible with Gatsby v5 (e.g., Node.js 18.0.0 or higher, with Node.js 20 and 22 being formally supported). Use a tool like `nvm` to manage Node.js versions.

Upgrade

Version history

7.16.0latest on npm

Audit

Dependencies

gatsbyrequiredPeer dependency, as this is a Gatsby plugin. Requires Gatsby v5 or newer.

prismjsrequiredPeer dependency, providing the core highlighting library and themes. Required for syntax highlighting to function.

gatsby-transformer-remarkrequiredRequired as a parent plugin for `gatsby-remark-prismjs` to process Markdown files. `gatsby-remark-prismjs` operates as a child plugin of `gatsby-transformer-remark`.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/gatsbyjs/gatsby ↗

packagehttps://www.npmjs.com/package/gatsby-remark-prismjs ↗

homepagehttps://www.gatsbyjs.com/plugins/gatsby-remark-prismjs/ ↗