{"id":13214,"library":"gatsby-remark-images","title":"Gatsby Remark Images","description":"gatsby-remark-images is a Gatsby plugin designed to enhance markdown-embedded images, making them responsive and optimized for production builds. It functions by processing images within markdown files through `gatsby-transformer-remark`, generating multiple width versions and setting `srcset` and `sizes` attributes for efficient, bandwidth-aware loading. A key feature is its \"blur-up\" technique, which uses a small, lightweight placeholder image that quickly loads and then transitions to the full-resolution image, improving perceived performance and preventing layout shifts. The plugin is currently at version `7.16.0` and is an integral part of the actively maintained Gatsby ecosystem, with updates often coinciding with new Gatsby framework releases. It critically depends on `gatsby-plugin-sharp` for its underlying image processing capabilities, enabling advanced optimizations like WebP conversion and quality compression.","status":"active","version":"7.16.0","language":"javascript","source_language":"en","source_url":"https://github.com/gatsbyjs/gatsby","tags":["javascript","gatsby","gatsby-plugin","image","markdown","remark","responsive images"],"install":[{"cmd":"npm install gatsby-remark-images","lang":"bash","label":"npm"},{"cmd":"yarn add gatsby-remark-images","lang":"bash","label":"yarn"},{"cmd":"pnpm add gatsby-remark-images","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Gatsby framework, required for any Gatsby plugin. This plugin is tightly coupled with Gatsby's node API.","package":"gatsby","optional":false},{"reason":"Image processing engine. gatsby-remark-images delegates all image manipulation tasks (resizing, generating multiple formats, blur-up) to gatsby-plugin-sharp.","package":"gatsby-plugin-sharp","optional":false},{"reason":"This plugin is designed to work specifically with gatsby-transformer-remark, which processes Markdown files into HTML and allows other remark plugins to hook into the transformation.","package":"gatsby-transformer-remark","optional":false}],"imports":[{"note":"This plugin is configured within your `gatsby-config.js` file as an entry in the `plugins` array, specifically nested under `gatsby-transformer-remark`. It does not expose direct JavaScript exports for use in components or utilities.","wrong":"import { GatsbyRemarkImages } from 'gatsby-remark-images'; // This plugin is not imported directly as a module.","symbol":"gatsby-remark-images","correct":"plugins: [\n  `gatsby-plugin-sharp`,\n  {\n    resolve: `gatsby-transformer-remark`,\n    options: {\n      plugins: [\n        {\n          resolve: `gatsby-remark-images`,\n          options: {\n            maxWidth: 590\n          }\n        }\n      ]\n    }\n  }\n]"},{"note":"Images must be referenced with relative paths within your markdown files to be processed by `gatsby-remark-images`. The special keyword `GATSBY_EMPTY_ALT` can be used to generate an empty `alt=\"\"` attribute.","wrong":"![External Image](https://example.com/image.jpg) // External images are not processed by this plugin.","symbol":"Markdown Image Syntax","correct":"![Alt text here](./image.jpg)\n\n![GATSBY_EMPTY_ALT](./image.png)"}],"quickstart":{"code":"// In your gatsby-config.js\nmodule.exports = {\n  plugins: [\n    `gatsby-plugin-sharp`, // Required for image processing\n    {\n      resolve: `gatsby-transformer-remark`,\n      options: {\n        plugins: [\n          {\n            resolve: `gatsby-remark-images`,\n            options: {\n              // It's important to specify the maxWidth (in pixels) of\n              // the content container as this plugin uses this as the\n              // base for generating different widths of each image.\n              maxWidth: 590,\n              linkImagesToOriginal: true // Optional: links processed images to their original source\n            }\n          }\n        ]\n      }\n    }\n  ]\n};","lang":"javascript","description":"This configuration snippet shows how to integrate `gatsby-remark-images` into your `gatsby-config.js`. It enables responsive image processing for markdown files, leveraging `gatsby-plugin-sharp` and setting a `maxWidth` for optimized image generation."},"warnings":[{"fix":"Upgrade Node.js to version 18.0.0 or higher. For Gatsby v5, ensure Node.js is within the `>=18.0.0 <26` range specified by the package's engines.","message":"This plugin, aligned with Gatsby v5, requires Node.js version 18 or higher. Deployments or local development environments running on older Node.js versions will fail.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Ensure your project's `package.json` specifies `gatsby: ^5.0.0-next` and `gatsby-plugin-sharp: ^5.0.0-next`. Upgrade Gatsby and `gatsby-plugin-sharp` if necessary.","message":"`gatsby-remark-images` version 7.x requires Gatsby v5 (`^5.0.0-next`) as a peer dependency. Using it with Gatsby v4 or earlier will lead to compatibility issues or failures.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Verify `gatsby-plugin-sharp` is installed (`npm install gatsby-plugin-sharp`) and correctly listed in `gatsby-config.js` *before* `gatsby-transformer-remark` and `gatsby-remark-images`.","message":"`gatsby-remark-images` relies entirely on `gatsby-plugin-sharp` for image processing. If `gatsby-plugin-sharp` is not installed and configured, or if there are issues with its native dependencies, `gatsby-remark-images` will not function.","severity":"gotcha","affected_versions":"*"},{"fix":"Carefully determine the `maxWidth` for your content area and configure it in `gatsby-config.js` options for `gatsby-remark-images`. For example: `options: { maxWidth: 800 }`.","message":"Failing to set an appropriate `maxWidth` in the plugin options, or setting it too low/high, can lead to sub-optimal responsive image generation or unnecessarily large images. The `maxWidth` should reflect the maximum width your markdown content area will occupy.","severity":"gotcha","affected_versions":"*"},{"fix":"Ensure all images intended for processing are stored locally within your project and referenced using paths relative to the markdown file they are embedded in. For external images, consider `gatsby-remark-external-links` or similar plugins.","message":"`gatsby-remark-images` only processes images referenced by *relative paths* within markdown files. Absolute paths or external URLs will be ignored by the plugin, appearing as regular images without responsiveness.","severity":"gotcha","affected_versions":"*"},{"fix":"Regularly update `gatsby`, `gatsby-plugin-sharp`, and `gatsby-remark-images` to their latest stable versions to benefit from security patches and performance improvements.","message":"Gatsby and its ecosystem plugins, including `gatsby-remark-images`, occasionally receive dependency updates to address security vulnerabilities (e.g., `body-parser`, `multer` were updated in recent Gatsby core releases). Running outdated versions can expose your project to known issues.","severity":"gotcha","affected_versions":"<7.16.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you have `gatsby-remark-images` and `gatsby-transformer-remark` installed (`npm install gatsby-remark-images gatsby-transformer-remark`) and correctly configured in your `gatsby-config.js` under the `plugins` array.","cause":"The `gatsby-remark-images` package is not installed or incorrectly referenced in `gatsby-config.js`, or `gatsby-transformer-remark` is missing.","error":"Error: Plugin 'gatsby-remark-images' not found."},{"fix":"Verify `gatsby-plugin-sharp` is installed (`npm install gatsby-plugin-sharp`) and configured *before* `gatsby-transformer-remark` in your `gatsby-config.js`.","cause":"This error typically indicates that `gatsby-plugin-sharp` is not installed, not configured, or there's an issue with your `gatsby-config.js` order, preventing image nodes from being transformed.","error":"Error: GraphQL error: Cannot query field \"childImageSharp\" on type \"MarkdownRemark\"."},{"fix":"Upgrade your Node.js environment to a supported version. For Gatsby v5, this typically means Node.js 18 or higher. Use a version manager like `nvm` (`nvm install 18 && nvm use 18`) to manage Node.js versions.","cause":"Your Node.js environment does not meet the minimum or compatible version requirements of Gatsby or its plugins (such as `gatsby-remark-images`).","error":"The engine \"node\" is incompatible with this module. Expected version \"20 || >=22\". Got \"18.6.0\""},{"fix":"Double-check your `gatsby-config.js` for `gatsby-remark-images` options, especially `maxWidth`. Ensure markdown image paths are relative. Also, inspect your browser's developer tools for any CSS overrides that might be affecting the plugin's generated image wrappers.","cause":"This usually means `gatsby-remark-images` is not correctly processing the images due to improper configuration (e.g., `maxWidth` missing, wrong image paths) or a conflict with other plugins/CSS.","error":"Markdown images are not responsive; they load as original size or cause layout shifts."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}