🍿 3 min. read

Initial Thoughts On Migrating from gatsby-transformer-remark to gatsby-plugin-mdx

Monica Powell

Yesterday, I decided tackle two things at once, live-streaming for the first time on Twitch 🎉 while updating this site to support MDX in addition to Markdown. MDX allows developers to write JSX in Markdown documents. I was interested in upgrading this blog to support MDX because from what I've seen it will enable me to produce more interactive and engaging blog content.

Move the slider below to navigate through my MDX journey so far and see MDX in action:


I adapted this slider from the one in this article on The Year of The Interactive Blog Post which features various examples of articles with immersive and engaging interactive experiences.

Here are some of my initial thoughts and findings from migrating this Gatsby site from using Markdown to MDX

Beware of Conflicting Plugins

While I was migrating from gatsby-transformer-remark to gatsby-plugin-mdx to allow my site to support .MDX files in addition to .MD files I followed the steps in this Gastby article on converting an existing Gatsby blog to use MDX. However, along the way I ran into an error accessing some of the fields that should be available for mdx nodes like body,timeToRead and excerpt.

error Cannot query field "body" on type "Mdx". Did you mean "rawBody"? graphql/template-strings

While debugging the issue I ended up commenting out all of the plugins in gatsbyRemarkPlugins and confirming that all of the data that should be available to query from mdx was available. I then re-added each plugin one-by-one to determine the culprit. In my case there was a conflict with gatsby-plugin-mdx and the plugin I use to generate Open Graph images for all of my posts (gatsby-plugin-my-social-cards). Until I replaced gatsby-plugin-my-social-cards with gatsby-remark-twitter-cards the plugin body,timeToRead and excerpt were not available to query.

I am not sure how common plugin conflicts like this are but it's definitely something to be aware of when migrating from gatsby-transformer-remark to gatsby-plugin-mdx.

Upgrade Your Syntax Highlighting

So far I am impressed with the developer experience of being able to use React components within MDX. However, in order to have better syntax highlighting for the AST of MDX files I needed to install an MDX specific plugin, VSCode MDX Plugin. The syntax highlighting with this plugin is signficantly better than without but it does seem a bit off. I am curious if there's a better syntax highlighting option for MDX.

Create Reusable Components for Repetitive Markdown

Aside from being able to support more interactivity in my writing I most excited about using MDX to be able to isolate certain functionality into distinct components. After migrating to MDX I was able to replace my ad-hoc Markdown based Table of Contents with a React component

diff with markdown table of contents vs MDX table of contents

The above screenshot of the code diff shows how I was able to replace the multiple lines of Markdown that were previously required for me to generate a Table of Contents with a one-line component that is able to parse the tableOfContents from the mdx nodes.

This article is very much a garden post 🌱 as I wanted to document my initial learnings and thoughts from updating my site to support mdx.

This article was published on May 26, 2020.

Subscribe to Newsletter

Thanks for reading "Initial Thoughts On Migrating from gatsby-transformer-remark to gatsby-plugin-mdx". Consider joining my newsletter to receive messages about new content, my thoughts on the web and learn about exclusive opportunities.


    I won’t send you spam. Unsubscribe at any time.


    • Colby Miller
    • Carol 😅
    • soumya dot dev ⚛️ 💥
    • _lululeon
    • Vladimír Kriška
    • Nicolas Beaussart
    • Miguel Piedrafita 🚀
    • Richard Haines
    • Gatsby
    • Daniel Rearden
    • Andri 🏡
    • chase adams
    • erdle 🍍
    • Kyle Gill
    • Sebastien Lorber
    • Kevin Viglucci
    • juicy j
    • ReactLadies #NYC
    • Jonny Buchanan
    • lauragift_
    • Laurie