Markdown, but make it useful ✨

This post is meant to be a quick cheat sheet. Each section shows: what you type and what you get.

the syntax you type
the result you get
whether it is plain markdown or MDX-only

Why markdown is nice

Markdown is fast. I can write with almost no friction, keep everything in Git, and still get a page that looks intentional instead of raw.

Headings 🔠

Type this:

# Main title
## Section heading
### Smaller heading

Result:

Main title

Section heading

Smaller heading

Bold, italic, inline code, and underline 🎨

Type this:

**bold**
*italic*
`inline code`

Result:

bold

italic

inline code

Underline is the first place where plain markdown gets limited. Standard markdown does not have real underline syntax, so in MDX you can use HTML. That is where MDX starts opening extra doors. Plain markdown stays lean; MDX gets expressive.

Type this:

<u>underlined text</u>

Result:

underlined text

Paragraphs 📝

Type this:

Write a paragraph normally.
 
Leave a blank line.
 
Then start the next paragraph.

Result:

Write a paragraph normally.

Leave a blank line.

Then start the next paragraph.

Links 🔗

Type this:

[Internal page](/projects)
[External site](https://nextjs.org/)

Result:

Internal page

External site

Lists 📚

Type this:

- one
- two
- three
 
1. first
2. second
3. third

Result:

one
two
three

first
second
third

Blockquotes 💬

Type this:

> Good tooling should remove friction, not add ceremony.

Result:

Good tooling should remove friction, not add ceremony.

Code blocks 💻

Type this:

```ts
export function formatStatus(isLive: boolean) {
  return isLive ? "Live now" : "Offline";
}
```

Result:

export function formatStatus(isLive: boolean) {
  return isLive ? "Live now" : "Offline";
}

Horizontal rule ➖

Type this:

---

Result:

Tables 📊

Type this:

| Format | Best For | Limitation |
| --- | --- | --- |
| Markdown | Fast writing | Mostly static content |
| MDX | Rich posts | More power means more responsibility |

Result:

| Format | Best For | Limitation | | --- | --- | --- | | Markdown | Fast writing | Mostly static content | | MDX | Rich posts | More power means more responsibility |

So what does MDX add? 🧪

MDX is basically markdown with React component support. Plain markdown is great for writing. MDX is what I use when a post needs something more expressive than text and basic formatting.

The short version

Markdown is content. MDX is content plus components. That means I can drop richer UI into a post when the writing actually benefits from it.

With MDX, I can do things like:

add custom callout boxes
use HTML like <u> when markdown does not support something
embed reusable React components
create richer layouts without abandoning markdown entirely

Example of an MDX-only component

Type this:

<Callout title="MDX unlock" tone="fuchsia">
  This box is a React component inside the post.
</Callout>

Result:

MDX unlock

This box is a React component inside the post.

When to use which

Use plain markdown when:

the post is mostly text
you want speed
a simple structure is enough

Use MDX when:

you want custom components
you need richer presentation
you want HTML or React-powered content inside the post

Final note

The point is not to turn every post into a miniature product. Most writing should still stay simple. The value of MDX is that when a post really does need something special, the format is ready for it 💡