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.

# Hello world!

You can use Markdown to create documents for [Gatsby](

<figure class="chart">
  <object data="chart.svg" type="image/svg+xml"></object>
  <figcaption>MDX adoption has increased 120% since last year.</figcaption>

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.

export const Figure = props => {
  return (
    <figure class="chart">
      <object data={} type="image/svg+xml"></object>

Now you can import this component into your Markdown document.

import { Figure } from './components/Figure';

# Hello world!

You can use Markdown to create documents for [Gatsby](

<Figure data="chart.svg" caption="MDX adoption has increased 120% since last year." />

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.

gatsby new my-mdx-starter

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.

npm install --save gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react

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