Since a year ago
• 6 minutes to read

How to write MDX

Write .mdx doesn't have to be hard

Author
Thyatdora Ny
Creative Fullstack Developer

1. What is MDX?

MDX is a markup language that lets you use JSX (basically HTML and React). Currently, its version is MDX 2.

You can import components, like interactive charts or alerts, and embed them within your content. This makes writing long-form content with components a blast 🚀.
You can learn more about MDX here.

This entire document is written in MDX.

2. How to setup environment for writing Markdown / MDX

You can write Markdown / MDX in any text editor you prefer. I would personally bias towards VSCode, but you can use any text editor you like. You can learn more about VSCode here.

2.1. Install VSCode

Start by downloading VSCode here.

2.2. Install VSCode Extensions

You can install VSCode extensions by clicking on the extension icon on the left side of the screen.

List of extensions I am using:

You can install as many extensions as you like. I would recommend you to install the ones I listed above. If you are not using or stop using them, consider uninstalling or disabling them to improve your overall VSCode performance or just create multiple VSCode profiles to manage your extensions.

3. Markdown First

MDX is Markdown first. This means that you can write Markdown and embed JSX components inside it. It is a fundmental knowledge to know how to write Markdown before jumping into MDX.

3.1. Basic Markdown Syntax

header.md
1# Header 1
2## Header 2
3### Header 3
4#### Header 4
5##### Header 5
6##### Header 6
header.md
1# Header 1
2## Header 2
3### Header 3
4#### Header 4
5##### Header 5
6##### Header 6
paragraph.md
1This is a paragraph.
paragraph.md
1This is a paragraph.
bold.md
1**bold text**
bold.md
1**bold text**
italic.md
1*italicized text*
italic.md
1*italicized text*
blockquote.md
1> blockquote a line 1
2> blockquote a line 2
3
4> blockquote b line 1
5> blockquote b line 2
blockquote.md
1> blockquote a line 1
2> blockquote a line 2
3
4> blockquote b line 1
5> blockquote b line 2
ordered-list.md
11. First item
22. Second item
33. Third item
ordered-list.md
11. First item
22. Second item
33. Third item
unordered-list.md
1- First item
2- Second item
3- Third item
unordered-list.md
1- First item
2- Second item
3- Third item
code.md
1`code`
code.md
1`code`
horizontal-line.md
1---
2
3___
horizontal-line.md
1---
2
3___
link.md
1[title](https://www.example.com)
link.md
1[title](https://www.example.com)
markdown.md
1![alt text](image.jpg)
markdown.md
1![alt text](image.jpg)
escape.md
1\*literal asterisks\*
escape.md
1\*literal asterisks\*

3.2. Markdown Extended Syntax

table.md
1| Syntax    | Description |
2| --------- | ----------- |
3| Header    | Title       |
4| Paragraph | Text        |
table.md
1| Syntax    | Description |
2| --------- | ----------- |
3| Header    | Title       |
4| Paragraph | Text        |
table-alignment.md
1| Syntax      | Description | Test Text     |
2| :---        |    :----:   |          ---: |
3| Header      | Title       | Here's this   |
4| Paragraph   | Text        | And more      |
table-alignment.md
1| Syntax      | Description | Test Text     |
2| :---        |    :----:   |          ---: |
3| Header      | Title       | Here's this   |
4| Paragraph   | Text        | And more      |
footnote.md
1Here's a simple footnote,[^1] and here's a longer one.[^bignote]
2
3[^1]: This is the first footnote.
4
5[^bignote]: Here's one with multiple paragraphs and code.
6
7    Indent paragraphs to include them in the footnote.
8
9    `{ my code }`
10
11    Add as many paragraphs as you like.
footnote.md
1Here's a simple footnote,[^1] and here's a longer one.[^bignote]
2
3[^1]: This is the first footnote.
4
5[^bignote]: Here's one with multiple paragraphs and code.
6
7    Indent paragraphs to include them in the footnote.
8
9    `{ my code }`
10
11    Add as many paragraphs as you like.
custom-header-id.md
1### My Great Heading {#custom-id}
custom-header-id.md
1### My Great Heading {#custom-id}
definition-list.md
1First Term
2: This is the definition of the first term.
3
4Second Term
5: This is one definition of the second term.
6: This is another definition of the second term.
definition-list.md
1First Term
2: This is the definition of the first term.
3
4Second Term
5: This is one definition of the second term.
6: This is another definition of the second term.
strikethrough.md
1~~The world is flat.~~ We now know that the world is round.
strikethrough.md
1~~The world is flat.~~ We now know that the world is round.
task-lists.md
1- [x] Write the press release
2- [ ] Update the website
3- [ ] Contact the media
task-lists.md
1- [x] Write the press release
2- [ ] Update the website
3- [ ] Contact the media

4. Moving to MDX

Moving from Markdown to MDX may seem like a significant leap, but with the right approach, it becomes a seamless transition.

4.1. Introduction to JSX

Here's a rundown of the fundamental JSX syntax:

basic-jsx.jsx
1function HelloWorld() {
2  return (
3    <div 
4      onClick={() => {
5        console.log('Vola!')
6      }}>
7        Hello World
8    </div>
9  )
10}
basic-jsx.jsx
1function HelloWorld() {
2  return (
3    <div 
4      onClick={() => {
5        console.log('Vola!')
6      }}>
7        Hello World
8    </div>
9  )
10}

Let's break it down. Here are writing a functional component called HelloWorld that returns a
<div>Hello World</div>. It has click event that logs Vola! to the console when clicked.

Key to take away here is you can write <div>Hello World</div> inside a javascript and that's the beauty of JSX syntax. By applying the same concept, you can start writing MDX.

hello-world.mdx
1# Hello World
2
3This is my very first markdown document. <div onClick={() => { console.log("Vola!") }}>Looks it's a jsx!</div>
hello-world.mdx
1# Hello World
2
3This is my very first markdown document. <div onClick={() => { console.log("Vola!") }}>Looks it's a jsx!</div>

4.2. Importing Components

You can enhance your MDX documents by importing and using components from other files. Here's how:

Suppose you have a component called HelloWorld in a file named hello-world.jsx within a components folder:

components/hello-world.jsx
1export default function HelloWorld() {
2  return (
3    <h1>Hello World</h1>
4  )
5}
components/hello-world.jsx
1export default function HelloWorld() {
2  return (
3    <h1>Hello World</h1>
4  )
5}

You can easily import and use this component in your MDX document as follows:

import-component.mdx
1import HelloWorld from './components/hello-world'
2
3<HelloWorld />
import-component.mdx
1import HelloWorld from './components/hello-world'
2
3<HelloWorld />

By importing and incorporating components, you can extend the functionality of your MDX content and create more dynamic and interactive documents.

5. Conclusion

In this guide, we've uncovered the power of MDX, bridging Markdown's simplicity with JSX's interactivity. MDX empowers you to create engaging content by seamlessly integrating components into your documents. Whether you're writing documentation, blog posts, or educational materials, MDX offers a creative canvas to bring your ideas to life. Embrace MDX, combine Markdown and JSX, and watch your content flourish.

Happy writing!