Code editor mockup highlighting MDX with embedded components and syntax highlighting
mdxastrocomponents

Using MDX in Astro

MDX lets you use JSX components inside your Markdown content. This means you can embed interactive elements, custom components, or Astro built-ins directly in your blog posts.

What is MDX?

MDX is a superset of Markdown that lets you write JSX. You can import and use any component from your src/components/ directory.

Example: Astro’s Built-in Code Component

The <Code> component provides syntax highlighting:

const message = 'Hello from MDX!';
console.log(message);

When to Use MDX

Use .mdx files when your post needs:

  • Interactive elements (accordions, tabs, demos)
  • Custom components (callout boxes, comparison tables)
  • Dynamic data rendered at build time

For simple text-only posts, plain .md files are fine and slightly faster to build.

Creating an MDX Post

Create a file with the .mdx extension in src/content/blog/:

src/content/blog/my-post.mdx

Then import components at the top of the frontmatter and use them anywhere in the body.

That’s all there is to it! 🎉