Markdown to MDX migration guide

Introduction

Migrating from traditional Markdown (.md) to MDX (.mdx) unlocks the ability to use typed, interactive React components inside your content. If you're moving to a modern CMS like TinaCMS or working in a Next.js-based static site, this guide shows how to automate the conversion of custom Markdown content into clean MDX.

At a glance

You need this if:

You're adopting MDX for React-based content rendering
Your Markdown files use custom containers e.g. YouTube embeds
You want to avoid manually rewriting thousands of files

Key Migration Challenges

Legacy shortcodes and custom syntax not MDX-compatible
MDX requires valid JSX — raw HTML and plugins won’t work
Markdown plugins are not portable
Manual conversion is slow and error-prone

Script Overview

We built a Python script that:

Recursively scans .md files
Detects custom blocks using regex
Replaces each with JSX components
Cleans up formatting artifacts (e.g. )
Outputs .mdx files

Block Types Supported

Here are the key Markdown patterns which the script converts into MDX components:

Note: Some examples are unique to the project it was developed for.

These reflect common patterns we used in the original Markdown content.

Example Conversion (Before & After)

Figure: Rendered email template

Running the Script

To convert a single file:

To convert all files:

After conversion, start your local TinaCMS site and browse the converted pages to make sure that custom blocks (videos, asides, emails, images, etc.) render correctly.

Extending the Script

Add new regex patterns for custom containers
Modify JSX output to match your component APIs
Tune parsing logic for edge cases or metadata

Final Notes

This script made it possible to convert thousands of Markdown files into clean, structured MDX suitable for modern frameworks.

If you're working on a similar migration and want help adapting or extending this approach, the team at SSW has experience with MDX and TinaCMS projects and can assist if needed.

→ View the script: convert_md_to_mdx.py

Last Edited: October 10, 2025