Skip to main content


Learn what MDX is, and how you can use it when creating content for your Gatsby site.

What is MDX?

MDX is an extension to Markdown that lets you include JSX in Markdown documents. MDX makes it possible to include React components in your Gatsby blog posts and pages.

Markdown defines a plain text syntax for HTML elements such as h1, strong, and a, but still supports inline HTML. An example Markdown document follows.

MDX takes this one step further, and makes it possible to use JSX in your Markdown documents. Try making the figure element into a Figure component.

Now you can import this component into your Markdown document.

If you’re creating a Gatsby site from scratch, the gatsby-starter-mdx-basic is the fastest way to add MDX support. Use the Gatsby CLI to create a new project with this starter as a base.

To use MDX with an existing Gatsby site, add the gatsby-plugin-mdx plugin. As with Gatsby itself, you can install it using npm. You’ll also need to install MDX itself, and the React implementation of MDX.

Then add gatsby-plugin-mdx to your plugins list in gatsby-config.js, and set the configuration options you prefer.

MDX enhances Markdown’s capabilities so that you can use React components anywhere in your Gatsby-powered site.

Learn more about MDX

Edit this page on GitHub