Home Tutorials Articles About Me Contact

What is MDX and how you can use it on your Gatsby blog

Published in Article

December 27, 2019

4 min read

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.

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 if you are curious).

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

There are many apps you can use to write Markdown, I talk about my favorite here.

After using it extensively on my 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.

Markdown supports HTML so, for example, if you want to have a particular heading in your article, you can still write:

<h2 id="special-heading">I am a special Heading</h2>

instead of writing the following, which would make impossible to add a custom id to the HTML tag.

## I am a special Heading

I like my Markdown to be as clean as possible so I tend to avoid putting too much HTML inside of it, but there are times where it can be useful.

Sometimes I felt like it would have been nice to implement that cool carousel component 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).

Unfortunately, in Markdown I would have not been able to do so and that is where I discovered MDX.

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:

import Carousel from "nuka-carousel";

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

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

test

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:

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.
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
Inside of gatsby-node.js, you need to replace mentions of allMarkdownRemark with allMdx
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.
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.
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.
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 they also have articles to implement MDX on a new blog, in case you are not coming from a pre-existing one like me.

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.

If you encounter any bug while using MDX please report them in Github at this link

Caveats for working with MDX

If you know how GatsbyJS works, you will know that each JS file in the pages folder will become a page. If you are working with Markdown files, this won’t matter but if you are using MDX then you need to be aware that each MDX file inside of that folder will also become a page.

So, for example, if you have a folder called blog in your pages folder, each .mdx file will become a page of URL Sitename/blog/fileName. If you don’t want to automatically generate pages and instead want to create your own, inside of gatsby-node then the solution it’s simple: move the blog folder outside of pages.

By doing that you will skip the automatic generation and instead you will be able to manually define the way you want those pages to be created in the gatsby-node file. Remember to update the import paths of your components in the MDX files when you move the folder!