Gatsby Remark PrismJS Plugin

Common errors

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

  cause `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.

  cause 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"

  cause 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.

Warnings

• 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`.
• gotcha This 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.
• gotcha Syntax 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.
• gotcha If 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`.
• gotcha Order 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.

Install

• npm install gatsby-remark-prismjs npm
• yarn add gatsby-remark-prismjs yarn
• pnpm add gatsby-remark-prismjs pnpm

Imports

• PrismJS Theme CSS
  wrong:

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

  correct:

  require("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)
  wrong:

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

  correct:

  require("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)
  wrong:

  import { Prism } from 'prismjs'

  correct:

  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.

Quickstart

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
```