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 to create new pages on your site.

🚀 Quick start

  1. Create a Gatsby MDX site.

  2. Initialize the MDX starter with the Gatsby CLI

    npx gatsby new my-mdx-starter https://github.com/ChristopherBiscardi/gatsby-starter-mdx-basic
    
  3. Run the dev server by changing directory to the scaffolded site and install dependencies

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

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

  1. Add gatsby-mdx and MDX as dependencies

    yarn add gatsby-mdx @mdx-js/mdx @mdx-js/tag
    
  2. Update your gatsby-config.js to use the gatsby-mdx plugin

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

What's next?

Go check out the guides to find out what else you can do with Gatsby and MDX!

edit this page on GitHub