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.

gatsby-config.js

🚀 Quick start

  1. Initialize the MDX starter with the Gatsby CLI

    npx gatsby new my-mdx-starter https://github.com/ChristopherBiscardi/gatsby-starter-mdx-basic
  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: [
       // ....
       `gatsby-mdx`,
     ],
    }
  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
Docs
Tutorial
Plugins
Blog
Showcase