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
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
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
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.
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.
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
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.