Do you know when to use MDX over Markdown?

Markdown and MDX are closely related — think of MDX as Markdown’s more powerful sibling. Markdown keeps things simple and readable, while MDX extends it to handle interactive and dynamic content using React (or other component frameworks).

TinaCMS is a great tool to build your site in MDX.

View MD & MDX examples.

When to use Markdown (.md)

Markdown is perfect for straightforward content. Think of it like writing a clear, no-frills document. You'll want to use Markdown when:

• You're creating something simple like a blog post, documentation, or guide
• Your team includes people who aren't tech experts
• You want your page to load quickly
• You just need basic formatting like headings, lists, and images

When to use MDX (.mdx)

MDX builds on Markdown by letting you embed components and logic directly inside your content. It’s still Markdown at heart — but with superpowers. Use MDX when:

• You need interactive features that go beyond static text
• You want to include custom components from different web frameworks
• Your content requires some programming logic
• You're creating tutorial content with live examples

Things to consider

MDX isn't perfect for every situation. Before you jump in, consider:

• Complexity - Since it's more advanced than plain Markdown, non-technical teams might find it tricky
• Performance - Too many fancy components can slow down your page
• Extra setup - You'll need to manage more technical dependencies

The golden rule ⭐️

Choose Markdown for simple, fast content. Choose MDX when you need more interactive and dynamic features.

The key is to start simple. Use Markdown for most of your content, and only switch to MDX when you truly need those extra capabilities.

More on migrating to MDX

Want to migrate your website to a modern CMS like 🦙 TinaCMS, and move from Markdown to MDX? Check out Markdown to MDX migration guide.

Video: Case Study - SSW migrating from MD to MDX for SSW Rules (5 min)