Learning MDX: Markdown + Components

If you already know Markdown, you’re ready for MDX. MDX is Markdown that can include JavaScript, JSX, and UI components. This guide shows you what MDX is, when to use it, and how to use it.

What you’ll learn: what MDX is, how it differs from Markdown, how to import and use components, and where to go next.

---

What is MDX?

MDX = Markdown + JSX. You keep writing normal Markdown (headings, lists, code blocks, etc.), and you can also:

• Import React, Vue, or Astro components
• Use those components like HTML tags in the middle of your text
• Write JSX (e.g. <MyComponent />) and export/import values

That lets you add interactive or dynamic bits—buttons, charts, callouts, embeds—without leaving your content file.

---

When to use MDX

• Stick with Markdown when your post is only text, code snippets, and images.
• Use MDX when you want:
  • Custom UI blocks (callouts, cards, tabs)
  • Interactive elements (buttons, toggles, demos)
  • Components that need props or logic

---

How MDX works in this project

This site uses Astro’s MDX integration. MDX files use the .mdx extension and live alongside .md files (for example in src/content/blog/). The same frontmatter (title, description, pubDate, etc.) works in both.

---

Using components in MDX

You import a component at the top of the file, then use it in the body like a tag.

1. Import at the top

Put your import right after the frontmatter (the --- block). Use a path relative to the MDX file.

---
title: 'My post'
---

import MyButton from '../../components/MyButton.astro';

2. Use the component in the content

Use the component like an HTML element. You can pass props (e.g. href, title).

Here is some **Markdown** and then a component:

<MyButton href="/learn">Go to guide</MyButton>

More Markdown here.

3. Example in this post

Below is a real example: we import HeaderLink at the top of this file and use it here. In the browser you’ll see a clickable button.

Embedded component in MDX

The MDX source for that looks like this:

import HeaderLink from '../../components/HeaderLink.astro';

<HeaderLink href="#" onclick="alert('clicked!')">
	Embedded component in MDX
</HeaderLink>

---

Important details

• File extension: Use .mdx for files that contain imports or JSX; use .md for plain Markdown.
• Imports: Only import at the top of the file. The path is relative to the MDX file.
• Interactivity: In Astro, components in MDX are static by default. To make them interactive (e.g. React/Vue components with client-side JS), you need client directives like client:load on the component usage or in the component definition.

---

Quick reference

You want to…	Use this
Write only text and code	Markdown (.md)
Add custom UI components	MDX (.mdx) + import
Use JSX in content	MDX (.mdx)
Interactive client components	MDX + client directives

---

Learn more

• MDX syntax and concepts
• Astro MDX guide
• Astro Markdown/MDX pages
• Astro client directives (for interactive components)

Previous: Learning Markdown — master Markdown first, then add MDX when you need components.