How to write MDX

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:

• Markdown All in One
• Markdown Preview Enhanced
• MDX
• MDX Preview

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.

• You can learn more about Markdown here.
• You can also read more about Github markdown

3.1. Basic Markdown Syntax

• Heading title or subtitle

<!-- title header.md -->
# Header 1
## Header 2
### Header 3
#### Header 4
##### Header 5
##### Header 6

• Paragraph a block of text

<!-- title paragraph.md -->
This is a paragraph.

• Bold important text

<!-- title bold.md -->
**bold text**

• Italic emphasized text

<!-- title italic.md -->
*italicized text*

• Blockquote a section that is quoted from another source

<!-- title blockquote.md -->
> blockquote a line 1
> blockquote a line 2

> blockquote b line 1
> blockquote b line 2

• Ordered List an ordered list

<!-- title ordered-list.md -->
1. First item
2. Second item
3. Third item

• Unordered List an unordered (bulleted) list

<!-- title unordered-list.md -->
- First item
- Second item
- Third item

• Code a piece of computer code

<!-- title code.md -->
`code`

• Horizontal Rule a thematic break in an HTML page

<!-- title horizontal-line.md -->
---

___

• Link a hyperlink, which is used to link from one page to another.

<!-- title link.md -->
[title](https://www.example.com)

• Image embed an image in an HTML page

<!-- title markdown.md -->
![alt text](image.jpg)

• Escaping escape characters which would otherwise have special meaning in Markdown’s formatting syntax

<!-- title escape.md -->
\*literal asterisks\*

3.2. Markdown Extended Syntax

• Table an HTML table

<!-- title table.md -->
| Syntax    | Description |
| --------- | ----------- |
| Header    | Title       |
| Paragraph | Text        |

• Table Alignments an HTML table with alignment

<!-- title table-alignment.md -->
| Syntax      | Description | Test Text     |
| :---        |    :----:   |          ---: |
| Header      | Title       | Here's this   |
| Paragraph   | Text        | And more      |

• Footnote define a footnote, which is used to give additional information about a topic

<!-- title footnote.md -->
Here's a simple footnote,[^1] and here's a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here's one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

    `{ my code }`

    Add as many paragraphs as you like.

• Heading Ids a heading id, which is used to link to a heading

<!-- title custom-header-id.md -->
### My Great Heading {#custom-id}

• Definition Lists a definition list, which is a list of terms, with a definition of each term

<!-- title definition-list.md -->
First Term
: This is the definition of the first term.

Second Term
: This is one definition of the second term.
: This is another definition of the second term.

• Strikethrough strikethrough, which usually indicates a deletion in the document

<!-- title strikethrough.md -->
~~The world is flat.~~ We now know that the world is round.

• Task Lists a task list, which is used to represent the tasks needed to be done

<!-- title task-lists.md -->
- [x] Write the press release
- [ ] Update the website
- [ ] 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:

function HelloWorld() {
  return (
    <div 
      onClick={() => {
        console.log('Vola!')
      }}>
        Hello World
    </div>
  )
}

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.

{/* title hello-world.mdx */}
# Hello World

This 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:

export default function HelloWorld() {
  return (
    <h1>Hello World</h1>
  )
}

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

{/* title import-component.mdx */}
import HelloWorld from './components/hello-world'

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