We recently cleaned the image related code in our Gatsby blog, and this is a tldr of what we learned.
Gatsby provides three options to handle images:
- Assets from filesystem (
import myImage from './myImage.png') - Gatsby image plugin (
<StaticImage ...>and it's dynamic variant) - Static folder (
<img ...>)
For blog posts written in MDX, none of these are particularly convenient though. For that, Gatsby provides an official plugin
This works quite seamlessly. We keep the image in the same folder as the .mdx and can then use the standard Markdown  syntax to include them in our posts.
Behind the scenes, it'll use the same method as Gatsby image plugin (#2, <StaticImage...> above) and support responsive variants using srcsets + blurred placeholders + async loading etc. More details are about this are in
The issue though is that there is only a global maxWidth option, and no way to specify it per image. Thankfully, there is a community plugin that allows us to do that.
This is intended as a drop-in replacement for gatsby-remark-images, and supports most of the same options. To configure this, one needs to add the following to gatsby-config.js:
{ resolve: 'gatsby-plugin-mdx', options: { gatsbyRemarkPlugins: [ { resolve: '@bonobolabs/gatsby-remark-images-custom-widths', options: { maxWidth: 640, quality: 80, backgroundColor: 'transparent', withWebp: true, linkImagesToOriginal: false, }, }, ], }, }, All the options are optional, the above are for illustration only. For example, we also needed to disable linkImagesToOriginal because otherwise all the blog images would get wrapped in anchor tags, causing the mouse cursor to change to a hand pointer (detracting from the reading experience).
Once it is configured, then using the plugin is simple. Just add an img tag to your MDX, and specify a width:
Some example **markdown** content. <img src="cat.png" width="310px" alt="Cat!"/> More markdown content. Type away! Rest of the image processing pipeline will work the same way. We will get a blurred variant that is shown while the actual image is being downloaded, and the image being downloaded will be the size appropriate to the user's screen.
For our blog, the convention we follow for now is that when adding images to MDX, we specify the 1x width but save the image at the 3x size. This way, Gatsby has high quality data to create large variants for users whose screens support 3x resolutions, but for other users it'll generate and fetch smaller images depending on their screen resolution and size.
For example, if we have a 240 px wide image (the 1x size), then we'll store a 720 px width image (the 3x size), and in the MDX we'll specify width="240".
We wouldn't let you come this far, talk of images, and not show you a cat pic!
So, here, meet Honey
On issue that still bugs us is lack of SVG support. For this we have to fallback to either option #1 (Assets from filesystem) or option #2 (Static folder). Maybe one of you would be kind enough to let us know (Twitter, Discord) if there is a simpler way!
Till next time, happy blogging 👩💻