What is MDX and how you can use it on your Gatsby blog
Tags: javascript, codenewbie, beginners, tutorial
Published: 2019-12-29 23:41:31

---
canonical_url: https://inspiredwebdev.com/what-is-mdx
---

> Check out my [blog](https://inspiredwebdev.com) for more articles or [Github](https://github.com/AlbertoMontalesi/The-complete-guide-to-modern-JavaScript) for my free-to-read JavaScript Ebook that covers all the new features from ES6 to 2019. 
If you want find a great place for interactive tutorials, i recommend [Educative](https://www.educative.io/explore?aff=BqmB) (Disclaimer: the link it's affiliate) where I'm currently finishing to build my JavaScript course.

Hi, I am Alberto Montalesi, a full-stack self-taught developer. I create practical JavaScript tutorials and courses on my website [inspiredwebdev.com](https://inspiredwebdev.com) to inspire other developers to grow and build the career that they want.

&nbsp;

## Why I love writing using Markdown

If you never used Markdown, let me introduce it to you in a few words. It's a simple conversion tool that allows you to write a simple text format that gets converted to valid HTML.

For example, to create headings (`h1`) you would do use `#`, to create bold tags you would use `**text**` and so on, you can read more about Markdown on this [guide](https://www.markdownguide.org/).

Since the moment I've started using Markdown, I fell in love with it. It's so simple, yet so powerful and I even went as far as using it to write a 300 pages book ([here](https://github.com/AlbertoMontalesi/The-complete-guide-to-modern-JavaScript) if you are curious).

It allows me to use the same format to write articles on my blog and DevTo and if I need, I can use tools like Pandoc to easily convert it to PDF or DOC.

After using it extensively on my [Gatsby blog](inspiredwebdev.com) I felt like I wanted it to do more, to be able to more easily implement custom HTML and JS inside of it.

Sometimes I felt like it would have been nice to implement that cool carousel component inside in the middle of my article, instead of putting it at the end, outside of the Markdown file and in the JSX template of the page (in the case of a Gatsby blog).

That is where I discovered **MDX**.

<br />

## What is MDX and why it's awesome

MDX is for JSX what MD is for JS. Thanks to it you can now easily import your components inside of an MDX file and seamlessly integrate them in your Markdown.

If now I want to add that nice carousel component in the middle of my article I can do it in just two lines:

First I need to import the component like so:

```JSX
import Carousel from "nuka-carousel";
```

and then I use it the same way I would in a JSX file:

```JSX
<Carousel props={whatever }/>
```

The rest of my article doesn't have to change at all, I can continue writing `##` for my `h2` etc.

> Remember that if you are referencing your components, the path needs to be relative to the folder where the **MDX** file is located.

<br />

## How to install it on my Gatsby blog

I had two pre-existing Gatsby blogs that I wanted to migrate to use **MDX** and it took me roughly 10 minutes to do that.

To summarize the steps you need to take to upgrade your existing blog:

1) Install the required packages like so: `npm install --save gatsby-plugin-mdx @mdx-js/mdx @mdx-js/react` and remember to uninstall your old `gatsby-transformer-remark` plugin.

2) Go inside your `gatsby-config` file and replace the old `gatsby-transformer-remark` with the new `gatsby-plugin-mdx` and be sure to add ` extensions: [`.mdx`, `.md`],` inside the options array of the plugin

3) Inside of `gatsby-node.js`, you need to replace mentions of `allMarkdownRemark` with `allMdx`

4) Find your `index.js` page or wherever you display a list of posts and replace all mentions of `allMarkdownRemark.edges` with `allMdx.edges`. Remember to replace it in the GraphQL query.

5) Inside of your single post template you need to replace `data.markdownRemark` with `data.mdx`. Again, remember to replace it in the GraphQL query too.

6) Inside of your single post template, add `import { MDXRenderer } from "gatsby-plugin-mdx"` and replace mentions of `html` with `body` both in the code and in the query.

7) In the last step, we need to replace the section where we use `dangerouslySetInnerHTML` with the new `<MDXRenderer>{post.body}</MDXRenderer>` and remember to replace `post.body` with the relevant variable name you are using in your template.

That should do it. During my process of upgrading, I've encountered a few errors but all related to some unclosed HTML tags in my Markdown files, once I fixed those minor issues everything was smooth. 

I bet your migration will also go smoothly.

If you need a more in-depth guide to upgrade, you should check out the official [Gatsby blog](https://www.gatsbyjs.org/blog/2019-11-21-how-to-convert-an-existing-gatsby-blog-to-use-mdx/) they also have articles to implement MDX on a new blog, in case you are not coming from a pre-existing one like me.

<br />

## Working with MDX

Working with **MDX** has been great so far, I haven't' encountered any problem and the ability to add components to my Markdown files, without having to give up the simplicity of the Markdown syntax, has been amazing.

If you are working on VSCode, you will have to install a new extension to enable syntax highlight. You can just search for **MDX** in the extension store and the first one that comes up will be good for you.

<br />

## Final Considerations

What are your thoughts about **MDX**? Was this the first time you heard about it? Did it catch your attention? Or have you been using it for a while? 

In that case, what is your experience with it? Leave a comment.

---

Thank you very much for reading. Follow me on [DevTo](https://dev.to/albertomontalesi) or on my blog at [inspiredwebdev](https://inspiredwebdev.com/) or on [twitter](https://twitter.com/montalesi)

<div className="promotional_banner">
<a href="http://a-fwd.to/5gUojI8" target="_blank">
<img alt="book banner" src="https://raw.githubusercontent.com/AlbertoMontalesi/The-complete-guide-to-modern-JavaScript/master/assets/banner.jpg" />
</a>
<span>Get my ebook on <a href="http://a-fwd.to/5gUojI8" target="_blank">Amazon</a> and <a href="https://leanpub.com/thecompleteguidetomodernjavascript2019" target="_blank">Leanpub</a></span>
</div>