MDX has revolutionized how developers think about content, blurring the lines between static documents and interactive applications. By allowing JSX within Markdown, it transforms content into a living part of your React ecosystem. But what happens when that content isn't static? What if it comes from a headless CMS, a database, or user input?
This is where traditional build-step MDX processing falls short and where mdx.do shines. At the heart of our service is a single, powerful function: mdx.compile. This post is a technical deep dive into how this function enables you to compile MDX content on the fly, unlocking a new world of dynamic, component-driven experiences.
Typically, integrating MDX into a project involves a build-time setup. Tools like Next.js or Vite plugins process your local .mdx files, bundling them into your application as static assets. This is highly efficient for websites where the content is known at build time.
However, the modern web is dynamic. Consider these scenarios:
In these cases, you can't rely on a build step. You need to process raw MDX strings in real-time. mdx.compile is the API-driven solution for this exact problem. It decouples MDX compilation from your build process, turning it into a lightweight, dynamic operation.
The mdx.compile function is designed for simplicity. It takes a raw MDX string and returns everything you need to render it as a React component.
Let's look at the basic workflow:
import { mdx } from "mdx.do";
const mdxContent = `
# Hello, MDX!
This is a JSX component rendered from a string:
<MyCustomComponent title="Welcome" />
And some dynamic expressions: {2024 - 1984} years have passed.
`;
// Compile the MDX string via the mdx.do API
const { code, frontmatter } = await mdx.compile(mdxContent);
// `code` can now be safely evaluated and rendered
// in your React application.
Let's break down the response:
Content is more than just its body. You need titles, authors, tags, and publication dates. MDX supports this through YAML frontmatter, and mdx.compile parses it for you automatically.
Simply add a YAML block enclosed by --- at the top of your MDX string:
---
title: 'Dynamic Content Made Easy'
author: 'The mdx.do Team'
published: true
tags: ['react', 'mdx', 'dynamic-content']
---
# My Awesome New Post
This post is about compiling MDX on the fly...
When you pass this string to mdx.compile, the returned frontmatter object will look like this:
{
"title": "Dynamic Content Made Easy",
"author": "The mdx.do Team",
"published": true,
"tags": ["react", "mdx", "dynamic-content"]
}
You can now use this structured data to set your page <title>, display author information, or filter posts by tags—all without manually parsing the content string.
Here's where the magic truly happens. MDX is not just about embedding HTML; it's about using your actual React components. mdx.compile fully supports this by allowing you to provide components at render time.
The process has two parts:
Let's see what the rendering part might look like in a React app (using a common pattern from libraries like next-mdx-remote or mdx-bundler):
// In your React page component (e.g., pages/post/[slug].jsx)
import { useMemo } from 'react';
import { getMDXComponent } from 'mdx-bundler/client'; // Or a similar client-side helper
// Your actual, live React components
import { InteractiveChart } from '../../components/InteractiveChart';
import { NewsletterSignup } from '../../components/NewsletterSignup';
// This is where you map string names to components
const mdxComponents = {
InteractiveChart,
NewsletterSignup,
};
// The `code` and `frontmatter` are passed as props from your server
export default function PostPage({ code, frontmatter }) {
// Memoize the component to avoid re-evaluating on every render
const Component = useMemo(() => getMDXComponent(code), [code]);
return (
<main>
<h1>{frontmatter.title}</h1>
<p>By {frontmatter.author}</p>
<div className="content">
{/* Render the MDX component, providing the component scope */}
<Component components={mdxComponents} />
</div>
</main>
);
}
// On the server-side (e.g., in getServerSideProps)
export async function getServerSideProps(context) {
const rawMdx = await fetchFromCMS(context.params.slug);
const { code, frontmatter } = await mdx.compile(rawMdx);
return { props: { code, frontmatter } };
}
This architecture is incredibly powerful:
The mdx.compile function is your gateway to building faster, more flexible, and more powerful content experiences with React. By handling compilation as a simple API call, mdx.do frees you from complex build tooling and opens the door to truly dynamic, component-driven content.
Ready to transform your content workflow? Explore the documentation and start compiling with mdx.compile today.