Skip to main content

Getting Started

The fastest way to get started with Gatsby + MDX is to use the MDX starter. This allows you to write .mdx files in src/pages in order to create new pages on your site.


🚀 Quick start

  1. Initialize the MDX starter with the Gatsby CLI

    npx gatsby new my-mdx-starter
  2. Run the dev server by changing directory to the scaffolded site and install dependencies

    cd my-mdx-starter/
    npm install
    gatsby develop
  3. Open the site running at http://localhost:8000!

  4. Update the MDX content by opening the my-mdx-starter directory in your code editor of choice and edit src/pages/index.mdx. Save your changes and the browser will update in real time!

Add MDX to an existing Gatsby site

If you already have a Gatsby site that you’d like to add MDX to, you can follow these steps for configuring the gatsby-mdx plugin:

  1. Add gatsby-mdx and MDX as dependencies

    yarn add gatsby-mdx @mdx-js/mdx @mdx-js/react

    If you’re upgrading from v0, check out the MDX migration guide.

  2. Update your gatsby-config.js to use the gatsby-mdx plugin

    module.exports = {
     plugins: [
       // ....
  3. Restart gatsby develop and add an .mdx page to src/pages

What’s next?

Go check out the writing MDX guide to find out what else you can do with Gatsby and MDX.

Edit this page on GitHub