DEV Community

Cover image for Convert the Gatsby default starter blog to use MDX
Scott Spence
Scott Spence

Posted on • Updated on • Originally published at

Convert the Gatsby default starter blog to use MDX

Photo by James Wheeler on Unsplash

In this guide we're going to cover converting the Gatsby default blog starter to use MDX.

All the cool kids are using Gatsby and MDX in their blogs these days. If you already have a blog that uses Gatsby but want to move onto the new hotness then this is the guide for you.


This guide is being used with the following dependency versions.

  • gatsby: 2.3.5
  • react: 16.8.6
  • react-dom: 16.8.6
  • gatsby-mdx: 0.4.5
  • @mdx-js/mdx: 0.20.3
  • @mdx-js/tag: 0.20.3

You can also check out the example code.

We're going to need some links, which are:

Import to CodeSandbox

For this example I'm going to be using the Gatsby starter blog and importing it into CodeSandbox, looking at the docs it says you can do this with the CodeSandbox import wizard linked, paste the
link in there and CodeSandbox will open the representation of the code on GitHub.

Now we can go about moving from using Gatsby transformer remark over to MDX.

Let's take a look at what we'll be changing for this example. But first we're going to need to import some dependencies to get MDX running in out Gatsby project.

With the add dependency button in CodeSandbox add the following dependencies:

  • gatsby-mdx
  • @mdx-js/mdx
  • @mdx-js/tag

We will also need to add dependencies for styled-components so may as well add them now as well:

  • gatsby-plugin-styled-components
  • styled-components
  • babel-plugin-styled-components

Files to change:

  • gatsby-node.js
  • gatsby-config.js
  • index.js
  • blog-post.js


First up we're going to need to change gatsby-node.js this is where all the pages and data nodes are generated.

Change all markdown remark occurrences with MDX, that's the initial GraphQL query in create pages, then again in the result.

initial gatsby node changes

Then change the node.internal.type in onCreateNode from MarkdownRemark to Mdx.

last gatsby node changes


Here we're going to replace gatsby-transformer-remark with gatsby-mdx

replace transformer remark with gatsby-mdx


Here we're going to alter the posts variable to take the Mdx edges.

replace all markdown edges

The Mdx edges are taken from the page query, which is also altered to use allMdx in place of allMarkdownRemark.

index page query


Now last on the list to get MDX working is the blog post template, we're going to need to import MDXRenderer from gatsby-mdx we're going to replace dangerouslySetInnerHTML with this shortly.

MDX renderer

Here's where we use it, we'll come onto post.code.body.

replace dangerously set html

Again in the query we're replacing markdownRemark with mdx and this time also doing away with html from the query and adding in code for body which we're using in our render method.

Now we're using MDX!

So now we can create a .mdx post, let's do that.

Import the styled-components dependencies:

Enter fullscreen mode Exit fullscreen mode

Then configure them in gatsby-config.js:

module.exports = {
  siteMetadata: {
    title: `Gatsby Starter Blog`,
  plugins: [
      resolve: `gatsby-source-filesystem`,
      options: {
Enter fullscreen mode Exit fullscreen mode

Now we can use styled-components, in src/components make a new component, I have called my one butt.js call yours what you like.

We're going to use this component in a .mdx document, first the component:

import styled from 'styled-components'

export const Butt = styled.button`
  background-color: red;
  height: 40px;
  width: 80px;
Enter fullscreen mode Exit fullscreen mode

Spicy, right! 🌢

Now we can include this component in a .mdx document so let's go ahead and create that, in content/blog make a new directory, I'm giving mine the imaginative name first-mdx-post, in there create
a index.mdx file and use the frontmatter from one of the other posts as an example of what to use:

title: My First MDX Post!
date: '2019-04-07T23:46:37.121Z'

# make a site they said, it'll be fun they said

more content yo!
Enter fullscreen mode Exit fullscreen mode

This will render a h1 and a p and we should see it render in our CodeSandbox preview.

Now we can go ahead and import our beautifully crafted button:

title: My First MDX Post!
date: '2019-04-07T23:46:37.121Z'

import { Butt } from '../../../src/components/button'

# make a site they said, it'll be fun they said

more content yo!

Enter fullscreen mode Exit fullscreen mode

Wrap up!

So, that's it, we've gone and converted the Gatsby starter blog from using Markdown Remark over to using MDX.

I hope you have found it helpful.

Thanks for reading πŸ™

Please take a look at my other content if you enjoyed this.

Follow me on Twitter or Ask Me Anything on GitHub.

Top comments (4)

dance2die profile image
Sung M. Kim

Thanks for the tutorial, Scott.

It looks like MDX can do everything that Markdown can but better with component support.

So would there be any case where one would not use MDX over regular markdown plugin?

spences10 profile image
Scott Spence

If you don't want to have JSX in your markdown then there's no real use for MDX if you're already using markdown, I guess.

aliahsan07 profile image
Ali Ahsan

did you forget to import the dependency @mdx-js/react?

spences10 profile image
Scott Spence

I didn't know it was needed until I watched Chris Biscardi's videos πŸ™ƒ

For the example I have done here there's no need for it.