Enhancing Your Astro Site with MDX: A Practical Guide

Introduction

Markdown has transformed the way developers write content for the web. Its simple syntax reduces the need for verbose HTML and automatically handles typographic niceties like converting straight quotes into curly ones. Astro, the modern static site generator, supports Markdown natively through .md files. However, the combination of Markdown and Astro can be taken to the next level with two powerful enhancements: MDX and Markdown Components. In this article, we’ll focus on MDX and show you how it unlocks new possibilities for content-rich Astro projects.

What is MDX?

MDX is a superset of Markdown that allows you to embed JSX and use components directly inside your Markdown files. This means you can leverage the simplicity of Markdown for writing prose while sprinkling in interactive or styled components from any frontend framework. In Astro, MDX integrates seamlessly, letting you import components from React, Svelte, Vue, or even native Astro components.

Example: Embedding Components in MDX

Here’s a quick demonstration. Suppose you have an Astro component and a Svelte component. In an MDX file, you can write:

---
// Frontmatter...
---
import AstroComp from '@/components/AstroComp.astro';
import SvelteComp from '@/components/SvelteComp.svelte';

<AstroComp />
<SvelteComp />

This flexibility makes MDX ideal for content-heavy pages, where you want to mix narrative text with rich elements like call-to-action buttons, charts, or embedded videos.

Simplifying Markup with MDX

One of the biggest advantages of MDX is that it retains all Markdown syntax within JSX blocks. For example, instead of writing verbose HTML for a card component, you can use Markdown inside a <div>:

<div class="card">
  ### Card Title

  Content goes here

  - List
  - Of
  - Items

  Second paragraph
</div>

Astro then processes this MDX into clean HTML:

<div class="card">
  <h2>Card Title</h2>
  <p>Content goes here</p>
  <ul>
    <li>List</li>
    <li>Of</li>
    <li>Items</li>
  </ul>
  <p>Second paragraph</p>
</div>

Notice how you can use ### for headings, - for list items, and skip paragraph tags entirely. Writing the same structure in raw HTML would be far more tedious.

Installing MDX in Astro

Adding MDX to your Astro project is straightforward thanks to the official integration. Run the following command in your project directory:

npx astro add mdx

This will install the necessary package and update your Astro configuration file. Once done, you can start creating files with the .mdx extension and use all the features described above.

Three Ways to Use MDX

These methods work for both standard Markdown and MDX files. Here are the primary approaches:

1. Import Directly into an Astro File

The simplest method is to import an MDX file as a component and use it directly in your template. For example:

---
import MDXContent from '../components/MyContent.mdx';
---

<MDXContent />

This makes MDX files function like reusable partials, perfect for things like testimonials, sidebars, or embedded content blocks.

2. Through Content Collections

For larger sites, content collections are the recommended way to manage MDX files. First, configure your collection to include both .md and .mdx patterns:

// src/content.config.js
import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/blog" }),
});

export const collections = { blog };

Then, in an Astro page, you can retrieve an entry and render it:

---
import { getEntry, render } from 'astro:content';
const { slug } = Astro.props;
const post = await getEntry('blog', slug);
const { Content } = await render(post);
---

<Content />

This approach gives you a powerful, type-safe way to handle multiple posts, complete with frontmatter validation.

3. Through a Layout

You can also apply a layout to all collected MDX files by setting a default layout in your content collection configuration or by using Astro’s built-in layout frontmatter property. This ensures consistent styling across all your content pages without repeating code.

Conclusion

MDX is a game-changer for Astro developers who want the best of both worlds: the simplicity of Markdown and the power of component-driven design. Whether you import MDX directly, leverage content collections, or use layouts, you’ll find that MDX streamlines your workflow and makes your content more expressive. Give it a try in your next Astro project, and experience the love between Markdown and Astro in a whole new way.