{"id":15442,"library":"gatsby-remark-prismjs","title":"Gatsby Remark PrismJS Plugin","description":"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.","status":"active","version":"7.16.0","language":"javascript","source_language":"en","source_url":"https://github.com/gatsbyjs/gatsby","tags":["javascript","gatsby","gatsby-plugin","prismjs","remark"],"install":[{"cmd":"npm install gatsby-remark-prismjs","lang":"bash","label":"npm"},{"cmd":"yarn add gatsby-remark-prismjs","lang":"bash","label":"yarn"},{"cmd":"pnpm add gatsby-remark-prismjs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, as this is a Gatsby plugin. Requires Gatsby v5 or newer.","package":"gatsby","optional":false},{"reason":"Peer dependency, providing the core highlighting library and themes. Required for syntax highlighting to function.","package":"prismjs","optional":false},{"reason":"Required as a parent plugin for `gatsby-remark-prismjs` to process Markdown files. `gatsby-remark-prismjs` operates as a child plugin of `gatsby-transformer-remark`.","package":"gatsby-transformer-remark","optional":false}],"imports":[{"note":"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.","wrong":"import \"prismjs/themes/prism-okaidia.css\"","symbol":"PrismJS Theme CSS","correct":"require(\"prismjs/themes/prism-okaidia.css\")"},{"note":"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.","wrong":"import \"prismjs/plugins/line-numbers/prism-line-numbers.css\"","symbol":"PrismJS Plugin CSS (e.g., Line Numbers)","correct":"require(\"prismjs/plugins/line-numbers/prism-line-numbers.css\")"},{"note":"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.","wrong":"import { Prism } from 'prismjs'","symbol":"Prism (for custom language definitions)","correct":"import Prism from 'prismjs'"}],"quickstart":{"code":"/* In gatsby-config.js */\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-source-filesystem`,\n      options: {\n        name: `blog`,\n        path: `${__dirname}/content/blog`,\n      },\n    },\n    {\n      resolve: `gatsby-transformer-remark`,\n      options: {\n        plugins: [\n          {\n            resolve: `gatsby-remark-prismjs`,\n            options: {\n              classPrefix: \"language-\",\n              showLineNumbers: true,\n              aliases: { js: \"javascript\", sh: \"bash\" },\n              languageExtensions: [\n                {\n                  language: \"customjs\",\n                  extend: \"javascript\",\n                  definition: {\n                    custom_keyword: /(customKeyword)/,\n                  },\n                },\n              ],\n            },\n          },\n        ],\n      },\n    },\n  ],\n}\n\n/* In gatsby-browser.js */\nrequire(\"prismjs/themes/prism-tomorrow.css\")\nrequire(\"prismjs/plugins/line-numbers/prism-line-numbers.css\")\n\n/* Example Markdown File (e.g., content/blog/my-post.md) */\n```js\n// JavaScript Example\nconst greeting = \"Hello, Gatsby!\";\nconsole.log(greeting);\n```\n\n```customjs\n// Custom JavaScript with customKeyword\nfunction customFunction() {\n  customKeyword console.log(\"This is a custom highlight.\");\n}\ncustomFunction();\n```\n\n```bash {numberLines: true}\n# Shell Example with line numbers\necho \"Hello from Bash\"\nnpm install\n```","lang":"javascript","description":"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."},"warnings":[{"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`.","message":"`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.","severity":"breaking","affected_versions":"<7.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add `require(\"prismjs/themes/<your-chosen-theme>.css\")` to your `gatsby-browser.js`. Replace `<your-chosen-theme>` with a valid PrismJS theme name.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Install `gatsby-transformer-remark` by running `npm install gatsby-transformer-remark` or `yarn add 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.","error":"Error: Cannot find module 'gatsby-transformer-remark'"},{"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.","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.","error":"Code blocks not highlighted / No syntax highlighting appears."},{"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.","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.","error":"error glob@11.0.3: The engine \"node\" is incompatible with this module. Expected version \"20 || >=22\". Got \"18.6.0\""}],"ecosystem":"npm"}