Check out my blog for more articles or Github 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 (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 to inspire other developers to grow and build the career that they want.
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 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 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.
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.
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 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.
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 or on my blog at inspiredwebdev or on twitter
Top comments (0)