Community Plugin

gatsby-rehype-inline-images

Downloads remote inline images and processes them with the Gatsby image tool chain. This plugin is part of the rehype collection and intended to be used with gatsby-transformer-rehype.

Install

yarn add gatsby-plugin-sharp gatsby-transformer-rehype gatsby-rehype-inline-images

How to use

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-plugin-sharp`,
  },
  {
    resolve: `gatsby-transformer-rehype`,
    options: {
        filter: node => (
            // this is an example (any node type can be selected)
            node.internal.type === `GhostPost`
        ),
        plugins: [
            {
                resolve: `gatsby-rehype-inline-images`,
                // all options are optional and can be omitted
                options: {
                    // all images larger are scaled down to maxWidth (default: maxWidth = imageWidth)
                    // maxWidth: 2000,
                    withWebp: true,
                    // disable, if you need to save memory
                    useImageCache: true,
                }
            },
        ],
    },
  },
]

Details

This plugin walks the htmlAst syntax tree and extracts all img tags. For each image found, the remote image data is fetched and put into a new file node. If the image format is supported by gatsby-plugin-sharp, the image is transformed into a fluid image. The fluid image is attached to the htmlAst coming from gatsby-transformer-rehype and the img tag is replaced by img-sharp-inline. That way, transformed images can be easily detected later and picked up by React components.

Unsupported image formats are directly copied to the /static folder and the image src attribute is updated to the new local image location. Both the file node and the processed images are cached in order to speed up build times on subsequent runs.

How to query

As this plugin mutates the htmlAst all changes are included in this syntax tree and in the transformed html:

{
  allGhostPost {
    edges {
      node {
        childHtmlRehype {
          htmlAst
          html
        }
      }
    }
  }
}

Image tag `img-sharp-inline` properties

An image that is transformed gets additional properties:

<img-sharp-inline htmlTag="" htmlClearProps="" parentClassName="" className="" fluidImg="" alt="" maxWidth="" />

where

htmlTag: original tag name before transformation (always img)
htmlClearProps: array of property names that should not be included in html output
parentClassName: class attribute from parent plus fluid-image
className: class attribute from replaced img
fluidImg: fluid image object as string (use JSON.parse(fluidImg) to transform back to object)
alt: alternative image title
maxWidth: maximum image width (number in pixels)

These properties give you the needed flexibility in your React components.

Properties injected into parent

CSS flexbox layouts need a little help in order to be able to display images with correct aspect ratios. For that reason, the following style property is added to the parent of the img tag:

style="flex: ${image.aspectRatio} 1 0"

where the image.aspectRatiois computed directly from the image. If you do not use CSS flexbox styles, the added style instruction won’t have any effect.

In addition, the attribute fluid-image is added to the parent’s class property, which you can use in your style sheets.

Use in React components

Instead of using the html it is highly recommended start from the htmlAst and compile it directly into a React component:

import React from 'react'
import rehypeReact from 'rehype-react'
import { ImgSharpInline } from '.'

const renderAst = new rehypeReact({
    Fragment: React.Fragment,
    createElement: React.createElement,
    components: { "img-sharp-inline": ImgSharpInline },
}).Compiler

const RenderContent = ({ htmlAst }) => (
    <div>
        { renderAst(htmlAst) }
    </div>
)

export default RenderContent

A minimal ImgSharpInline component may look like:

import React from 'react'
import Img from 'gatsby-image'

const ImgSharpInline = ({ parentClassName, className, fluidImg, alt }) => (
    <Img
        className={className}
        fluid={fluidImg && JSON.parse(fluidImg)}
        alt={alt}
    />
)

export default ImgSharpInline

This will make your inline images fully responsive and plays nicely with all gatsby-image features such as the blur-up effect.

Caveats

If your site contains many inline images, your build times may be considerably increased by using this plugin. Every image needs to be downloaded and processed which are network and computationally heavy tasks. This plugin utilizes the cache, so subsequent builds will be fast. Property injection into the parent has been hard-coded — this could be made configurable. If that limits your use case, let me know.

Troubleshooting

Please always clear the cache with yarn clean before reporting a bug to this project.