Skip to main content

MDX (@mdx-js/rollup) vs Runtime Markdown Rendering: Technical Comparison

Date: February 14, 2026 Author: Claude (Sonnet 4.5) Purpose: Comprehensive technical analysis for architectural decision-making

Executive Summary​

DimensionMDX (@mdx-js/rollup)Runtime Markdown (react-markdown)
CompilationBuild-time (no runtime)Runtime parsing on every render
Performance100% faster runtime (v2)Parsing overhead, can use memoization
Bundle Size250% smaller (v2), ~no runtime costLightweight, ~4.6 kB gzipped
InteractivityFull JSX embedding, React hooksNo component embedding
Search IndexingRequires text extractionRaw markdown readily available
AuthoringJSX knowledge requiredPure markdown, non-technical friendly
SecurityJSX execution vectorsSafer by default (no raw HTML)
HMR SupportYes (via Vite)N/A (runtime rendering)

1. Build-Time vs Runtime Rendering​

MDX Build-Time Compilation​

Architecture:

  • MDX compiles to JavaScript during the build phase
  • No runtime compilation overhead
  • Final output is pure JavaScript/JSX components

Performance Characteristics:

"MDX has no runtime, with all compilation occurring during the build stage" — MDX Documentation

"MDX v2 made the bundle size of @mdx-js/mdx more than three times as small (250% smaller), along with achieving 25% faster compilation and 100% faster runtime performance" — MDX v2 Blog Post

Build Performance Considerations:

  • Bundlers are not optimized for compiling hundreds of MDX files
  • File-based routing of markdown files in Next.js and Remix can be slow
  • Solution: On-demand compilation where content is only loaded when requested
  • Optimization: Tree shaking removes unused code from bundles

Code Example (vite.config.js):

import mdx from '@mdx-js/rollup'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    // CRITICAL: enforce: 'pre' required when using with @vitejs/plugin-react
    { enforce: 'pre', ...mdx({/* jsxImportSource: …, otherOptions… */}) },
    react({ include: /\.(jsx|js|mdx|md|tsx|ts)$/ })
  ]
})

"When using @vitejs/plugin-react together with @mdx-js/rollup, you must force @mdx-js/rollup to run in the pre phase before it by using {enforce: 'pre', ...mdx({/* options */})}" — MDX Rollup Discussion

Runtime Markdown Rendering​

Architecture:

  • react-markdown uses the unified pipeline: markdown → remark (MDAST) → remark-rehype → rehype → React components
  • Parsing happens on every render unless memoized
  • Text-to-AST conversion is computationally expensive

Performance Characteristics:

"Markdown rendering involves parsing plain text into HTML elements which can be computationally expensive, with parsing converting Markdown syntax into an abstract syntax tree (AST) and rendering transforming the AST into HTML elements" — Understanding Performance Impact

Optimization Strategies:

  1. Memoization: Use React.memo to prevent unnecessary re-renders
  2. Pre-rendering: Render markdown in static build phase
  3. Lazy loading: Load markdown content only when needed

Performance Trade-offs:

  • Runtime overhead from parsing on every render
  • Plugin ecosystem (remark/rehype) can introduce additional processing time
  • Virtual DOM approach allows React to efficiently update only changed content

Bundle Size:

"Markdown renders fast because there is no compilation, and Markdown is simply text, so Markdown files can be sent and rendered quicker than other content" — MD vs MDX Guide

"Markdown has a lighter weight with no JavaScript overhead, while MDX has more processing required and a larger bundle size with JavaScript dependency" — MDX vs Markdown Comparison

2. JSX Embedding Capabilities​

MDX: Full Component Embedding​

Import/Export Syntax:

---
title: "My Interactive Document"
---

import { Chart } from './components/Chart.js'
import { useState } from 'react'

export const metadata = {
  author: 'John Doe',
  publishedAt: '2026-02-14'
}

# {title}

Here's an interactive chart:

<Chart color="#fcb32c" year={2026} />

## Counter Example

export const Counter = () => {
  const [count, setCount] = useState(0)
  return (
    <button onClick={() => setCount(count + 1)}>
      Clicked {count} times
    </button>
  )
}

<Counter />

Key Capabilities:

  • Direct JSX embedding: Use <ComponentName /> syntax inline
  • Import from anywhere: npm packages (import { Box } from 'rebass') or local files
  • Named exports: export const metadata = {...} accessible from parent imports
  • Default export: The MDX file itself is a React component
  • Props support: Pass runtime data via props.variableName

"MDX allows you to import components like import {Chart} from './snowfall.js' and embed them in markdown content with JSX syntax, such as <Chart color=\"#fcb32c\" year={year} />" — MDX Documentation

Layout Pattern:

export default function Layout({children}) {
  return <main className="prose">{children}</main>
}

# Content goes here

"A layout can be defined from within MDX using a default export" — Using MDX Guide

Importing MDX Files:

import Post from './post.mdx'
import * as PostData from './post.mdx'

// Default export is a function component
<Post />

// Access named exports
console.log(PostData.metadata) // {author: 'John Doe', ...}

Runtime Markdown: No Component Embedding​

Limitation:

"If you instead want to use JavaScript and JSX inside markdown files, use MDX" — react-markdown prioritizes safe, predictable markdown-to-React conversion over runtime code execution" — react-markdown README

What You CAN Do:

  • Component substitution: Map HTML tags to custom React components
  • Plugin transformations: Modify AST before rendering
  • Custom renderers: Define how specific markdown elements render

Example:

import ReactMarkdown from 'react-markdown'

const MarkdownComponents = {
  h1: ({children}) => <h1 className="text-4xl font-bold">{children}</h1>,
  code: ({inline, children}) =>
    inline ? <code className="bg-gray-100">{children}</code> : <CodeBlock>{children}</CodeBlock>
}

<ReactMarkdown components={MarkdownComponents}>
  {markdownContent}
</ReactMarkdown>

Critical Difference:

  • MDX: Authors embed components inside markdown files
  • react-markdown: Developers define component mappings outside markdown content

3. Search Capabilities​

MDX: Compiled JavaScript Challenge​

Problem:

"MDX does not support compiledContent(). A custom plugin can extract plain text and inject it to the frontmatter object, and later when building the index the plain text can be pulled back out of the frontmatter" — Client-Side Search Guide

Text Extraction Required:

  1. Use rehype plugin to extract plain text from compiled HTML
  2. Store extracted text in frontmatter or separate index
  3. Build search index at build time
  4. Ship search index to client (JSON file)

Modern Solutions:

Pagefind (Recommended for MDX):

"Pagefind is a static search library that indexes HTML files and provides lightning-fast, client-side full-text search — all with no server required" — Pagefind Documentation

Nextra Implementation:

"Nextra indexes your content automatically at build-time and performs incredibly fast full-text search via Pagefind. For MDX pages while using nextra-theme-docs you don't need to add data-pagefind-body attribute" — Nextra Search Documentation

Configuration:

<!-- Mark content for indexing -->
<div data-pagefind-body>
  <!-- MDX compiled HTML output -->
</div>

<!-- Exclude elements -->
<nav data-pagefind-ignore>Navigation</nav>

MiniSearch vs Lunr:

FeatureMiniSearchLunr.js
Index Size<50% of LunrBaseline
MutabilityAdd/remove docs anytimeImmutable after creation
Stemming/LanguageDIY pluginsBuilt-in
Best ForMDX with frequent updatesStatic, build-once indexes

"MiniSearch index takes sensibly less space than Lunr's, typically using less than half of the space used by Lunr for the same collection" — MiniSearch Documentation

Runtime Markdown: Direct Access​

Advantage:

  • Raw markdown text available at runtime
  • No extraction step required
  • Index directly from markdown source

Example:

import { matter } from 'vfile-matter'
import MiniSearch from 'minisearch'

// Load all markdown files
const documents = markdownFiles.map(file => {
  const parsed = matter(file.content)
  return {
    id: file.path,
    title: parsed.data.title,
    content: parsed.content, // Raw markdown text
    ...parsed.data
  }
})

// Build search index
const miniSearch = new MiniSearch({
  fields: ['title', 'content'],
  storeFields: ['title', 'path']
})

miniSearch.addAll(documents)

Trade-off:

  • Easier indexing workflow
  • But requires shipping raw markdown to client (larger payload)
  • No interactive components in content

4. Developer Control​

MDX: Full React Capabilities​

React Hooks Support:

"React's useState and useEffect Hooks can be used within MDX to fetch, display, and update content, such as fetching user data from an API and displaying it within the MDX file" — Advanced MDX Dynamic Content

useState Example:

import { useState } from 'react'

export const DynamicGreeting = () => {
  const [name, setName] = useState('')

  return (
    <div>
      <input
        value={name}
        onChange={(e) => setName(e.target.value)}
        placeholder="Enter your name"
      />
      <p>Hello, {name || 'stranger'}!</p>
    </div>
  )
}

<DynamicGreeting />

useEffect Example:

import { useState, useEffect } from 'react'

export const UserData = () => {
  const [user, setUser] = useState(null)
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    fetch('/api/user')
      .then(res => res.json())
      .then(data => {
        setUser(data)
        setLoading(false)
      })
  }, [])

  if (loading) return <p>Loading...</p>
  return <div>Welcome, {user.name}!</div>
}

<UserData />

Critical Rule:

"You can only call Hooks at the top level of your React function" — React Hooks Rules

Props Handling:

# {props.title}

Published on {props.publishedAt}

{props.showAuthor && <p>By {props.author}</p>}
// Parent component
<MDXContent
  title="My Article"
  publishedAt="2026-02-14"
  author="John Doe"
  showAuthor={true}
/>

Component Customization:

"The components prop accepts an object mapping component names to replacement components. The special components.wrapper surrounds entire content sections" — MDX Using Guide

import Article from './article.mdx'

const components = {
  h1: ({children}) => <h1 className="custom-h1">{children}</h1>,
  wrapper: ({children}) => <article className="prose">{children}</article>
}

<Article components={components} />

Runtime Markdown: Limited to Markdown Syntax​

What You Control:

  • Component mapping (tag → React component)
  • URL transformation functions
  • Allow/disallow specific HTML tags
  • remark/rehype plugin configuration

What Authors Control:

  • Only markdown syntax
  • No JavaScript
  • No state management
  • No dynamic behavior

Example Customization:

<ReactMarkdown
  remarkPlugins={[remarkGfm, remarkMath]}
  rehypePlugins={[rehypeKatex, rehypeHighlight]}
  components={{
    code: CustomCodeBlock,
    a: ({href, children}) => <Link to={href}>{children}</Link>
  }}
  urlTransform={(url) => sanitizeUrl(url)}
  disallowedElements={['script', 'iframe']}
>
  {markdownContent}
</ReactMarkdown>

5. Content Authoring Workflow​

MDX: Developer-Centric​

Requirements:

  • Knowledge of React/JSX syntax
  • Understanding of component imports
  • Familiarity with JavaScript (for hooks/logic)

Advantages:

  • Full programmatic control
  • Reusable component library
  • Type safety with TypeScript (.mdx.d.ts files)

Challenges for Non-Technical Authors:

  • Steeper learning curve
  • Syntax errors can break compilation
  • Need understanding of component APIs

Example Cognitive Load:

---
title: "Complex Document"
---

import { Chart, DataTable } from '@/components'
import { useState, useEffect } from 'react'

export const ChartController = ({data}) => {
  const [view, setView] = useState('bar')
  return (
    <>
      <select onChange={(e) => setView(e.target.value)}>
        <option value="bar">Bar Chart</option>
        <option value="line">Line Chart</option>
      </select>
      <Chart type={view} data={data} />
    </>
  )
}

# Sales Report

<ChartController data={salesData} />

Non-technical author sees: Complex code requiring React knowledge

Runtime Markdown: Content-Centric​

Requirements:

  • Only markdown syntax
  • Optional: YAML frontmatter

Advantages:

  • Simple, universal format
  • Non-technical authors can contribute
  • Easy to learn and validate
  • Portable across systems

Content Management:

---
title: "Simple Document"
author: "Jane Smith"
date: 2026-02-14
---

# Sales Report

Here are the quarterly results:

| Quarter | Revenue |
|---------|---------|
| Q1      | $1.2M   |
| Q2      | $1.5M   |

For detailed analysis, see [Q2 Report](./q2-analysis.md).

Separation of Concerns:

  • Authors: Focus on content in markdown
  • Developers: Control presentation via React components
  • Designers: Style via CSS/Tailwind

"For most blog posts and basic content, stick with Markdown. The key is to start simple and use Markdown for most of your content, switching to MDX only when you truly need those extra capabilities" — MDX vs Markdown Guide

6. Vite Plugin Integration​

Complete Configuration Example​

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import mdx from '@mdx-js/rollup'
import remarkFrontmatter from 'remark-frontmatter'
import remarkMdxFrontmatter from 'remark-mdx-frontmatter'
import remarkGfm from 'remark-gfm'
import rehypeHighlight from 'rehype-highlight'

export default defineConfig({
  plugins: [
    // CRITICAL: enforce: 'pre' required with @vitejs/plugin-react
    {
      enforce: 'pre',
      ...mdx({
        // jsxImportSource: '@emotion/react', // Optional: custom JSX runtime
        remarkPlugins: [
          remarkGfm,              // GitHub Flavored Markdown
          remarkFrontmatter,      // Parse YAML frontmatter
          remarkMdxFrontmatter    // Export frontmatter as const
        ],
        rehypePlugins: [
          rehypeHighlight         // Syntax highlighting
        ],
        // development: true,     // Auto-set by Vite
        // providerImportSource: '@mdx-js/react' // For MDXProvider
      })
    },
    react({
      include: /\.(jsx|js|mdx|md|tsx|ts)$/  // Process .mdx files
    })
  ]
})

Package.json Requirements​

{
  "type": "module",  // CRITICAL: MDX packages are ESM-only
  "dependencies": {
    "@mdx-js/rollup": "^3.0.0",
    "@mdx-js/react": "^3.0.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^4.2.0",
    "vite": "^5.0.0",
    "remark-frontmatter": "^5.0.0",
    "remark-mdx-frontmatter": "^4.0.0",
    "remark-gfm": "^4.0.0",
    "rehype-highlight": "^7.0.0"
  }
}

"This package is ESM only. In Node.js (version 16+), install with npm. You should add \"type\": \"module\" to your package.json" — MDX Rollup Documentation

Compatibility Notes​

Vite 5 Issue:

"@mdx-js/rollup stops working on Vite v5" — Some versions have compatibility issues requiring workarounds or version pinning — GitHub Issue #2413

Alternative Plugin:

  • vite-plugin-mdx (third-party wrapper around @mdx-js/rollup)
  • May provide additional Vite-specific optimizations

7. Hot Module Replacement (HMR)​

Vite HMR Architecture​

"Vite swaps only the exact file you changed, with measured latency between 10-20 ms compared to Webpack's 500+ ms. Your application state remains intact, and your development flow stays uninterrupted" — Strapi Vite Guide

How HMR Works:

  1. Browser maintains WebSocket connection to dev server
  2. File change detected → server analyzes dependencies
  3. Server sends targeted update instructions to client
  4. Client hot-swaps module without full page reload
  5. Application state preserved across updates

MDX HMR Support​

YES - MDX supports HMR in Vite:

  • Changes to .mdx files trigger hot updates
  • React component state preserved during updates
  • Instant preview of content changes

HMR Boundary:

<!-- Counter.mdx -->
import { useState } from 'react'

export const Counter = () => {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>{count}</button>
}

<Counter />

Developer Experience:

  1. Edit markdown content → instant update, state preserved
  2. Edit component logic → hot swap, state reset (intentional)
  3. Edit imports → full reload (dependency change)

API Access:

if (import.meta.hot) {
  import.meta.hot.accept((newModule) => {
    // Custom HMR logic
  })
}

"Vite exposes its manual HMR API via the special import.meta.hot object. The import.meta.hot API provides developers with granular control over how modules respond to updates" — Vite HMR API

Runtime Markdown HMR​

N/A - No build step, no HMR needed:

  • Markdown content is data, not code
  • Changes require re-fetching markdown source
  • No module replacement concept

Development Pattern:

function MarkdownViewer() {
  const [content, setContent] = useState('')

  useEffect(() => {
    // In dev: poll for changes or use file watcher
    fetch('/api/markdown/article.md')
      .then(res => res.text())
      .then(setContent)
  }, [])

  return <ReactMarkdown>{content}</ReactMarkdown>
}

Trade-off:

  • No HMR complexity
  • But requires custom dev server for live preview
  • Or manual browser refresh

8. Bundle Size Impact​

MDX Bundle Analysis​

Core Runtime Cost:

"MDX v2 made the bundle size of @mdx-js/mdx more than three times as small (250% smaller)" — MDX v2 Blog

What Ships to Client:

  • ✅ Compiled JSX components (minimal overhead)
  • ✅ React runtime (already in app)
  • ❌ NO MDX compiler (build-time only)
  • ❌ NO markdown parser

Example Build Output:

// article.mdx compiled to:
export default function MDXContent(props) {
  return (
    <div className="mdx">
      <h1>Article Title</h1>
      <p>Content here</p>
      <Chart data={props.data} />
    </div>
  )
}

Bundle Impact Per MDX File:

  • Equivalent to hand-written JSX
  • No parser overhead
  • Tree-shaking removes unused components

Warning:

"Using MDX in a runtime environment introduces a substantial amount of overhead and dramatically increases bundle sizes" — MDX Runtime Discussion

@mdx-js/runtime Package:

  • 851.1 kB gzipped (DO NOT USE in production)
  • Only for server-side rendering or build tools
  • Not recommended for client-side compilation

Runtime Markdown Bundle Analysis​

Core Dependencies:

  • react-markdown: ~4.6 kB gzipped
  • unified + remark + rehype ecosystem: varies by plugins
  • Typical total: 15-30 kB gzipped (with common plugins)

What Ships to Client:

  • ✅ Markdown parser (remark)
  • ✅ HTML transformer (rehype)
  • ✅ React renderer
  • ✅ Raw markdown content (text payload)

Bundle Size Comparison:

ApproachParserContentTotal
MDX0 KB (build-time)Compiled JSX (~5 KB/file)~5 KB/file
Runtime~15 KB (one-time)Raw markdown (~2 KB/file)~15 KB + 2 KB/file

Break-Even Point:

  • 1 file: Runtime smaller
  • 5 files: ~equal
  • 10+ files: MDX smaller
  • 100+ files: MDX significantly smaller

Optimization:

"MDX is rendered into HTML at build time (rather than runtime), meaning pages are as quick as any HTML page, and writing in MDX has no negative performance impact on your site. However, too many fancy components can slow down your page" — MDX Performance Guide

9. Frontmatter Handling​

MDX Frontmatter Options​

Option 1: ESM Exports (Recommended)

export const metadata = {
  title: 'My Article',
  author: 'John Doe',
  publishedAt: '2026-02-14',
  tags: ['react', 'mdx']
}

# {metadata.title}

By {metadata.author}
// Import and access
import Article, { metadata } from './article.mdx'

console.log(metadata.title) // 'My Article'
<Article />

Advantages:

  • Type-safe with TypeScript
  • Direct JavaScript access
  • No parsing required

Option 2: YAML Frontmatter + Plugins

---
title: My Article
author: John Doe
publishedAt: 2026-02-14
tags:
  - react
  - mdx
---

# {frontmatter.title}

By {frontmatter.author}

Required Plugins:

// vite.config.js
import remarkFrontmatter from 'remark-frontmatter'
import remarkMdxFrontmatter from 'remark-mdx-frontmatter'

mdx({
  remarkPlugins: [
    remarkFrontmatter,        // Parse YAML
    remarkMdxFrontmatter      // Export as const
  ]
})

Output:

export const frontmatter = {
  title: 'My Article',
  author: 'John Doe',
  publishedAt: '2026-02-14',
  tags: ['react', 'mdx']
}

"remark-frontmatter adds support for frontmatter but doesn't parse the data inside them. remark-mdx-frontmatter takes frontmatter content and outputs it as JavaScript exports, supporting both YAML and TOML frontmatter data" — MDX Frontmatter Guide

Option 3: File System Extraction (Build-Time)

import { read } from 'to-vfile'
import { matter } from 'vfile-matter'

const file = await read('article.mdx')
matter(file)
console.log(file.data.matter) // {title: 'My Article', ...}

Use Case: Extract metadata for routing, sitemap generation, RSS feeds

TypeScript Type Definitions:

// article.mdx.d.ts
export { default } from '*.mdx'
export const metadata: {
  title: string
  author: string
  publishedAt: string
  tags: string[]
}

Runtime Markdown Frontmatter​

gray-matter (Standard Approach):

import matter from 'gray-matter'

const markdown = `---
title: My Article
author: John Doe
---

# Content here`

const { data, content } = matter(markdown)

console.log(data.title)    // 'My Article'
console.log(content)       // '# Content here'

Integration with react-markdown:

function MarkdownPage({ source }) {
  const { data: frontmatter, content } = matter(source)

  return (
    <article>
      <h1>{frontmatter.title}</h1>
      <p className="author">By {frontmatter.author}</p>
      <ReactMarkdown>{content}</ReactMarkdown>
    </article>
  )
}

Advantages:

  • Simple, well-established pattern
  • Works with any markdown source
  • No build configuration needed

Comparison:

FeatureMDXRuntime Markdown
ParsingBuild-time or ESMRuntime (gray-matter)
AccessImport named exportParse on load
Type SafetyTypeScript .d.tsManual types
PerformanceZero runtime costParse every render

10. Real-World Adoption​

Documentation Site Generators​

Docusaurus (Meta/Facebook):

  • Default: MDX
  • Philosophy: Component-rich, interactive documentation
  • Market Share: 4x more popular than VitePress
  • Users: Facebook, Meta, Supabase, Hasura

"Docusaurus supports MDX by default, and the Docusaurus static site generator is 4 times more popular than VitePress" — Docusaurus vs VitePress

Nextra (Vercel):

  • Default: MDX
  • Philosophy: MDX-first, Next.js powered
  • Features: Auto-indexing with Pagefind
  • Users: Vercel, Next.js docs, Turbo

"Nextra is a lightweight static site generator built on top of Next.js. The framework is MDX-first, allowing you to seamlessly embed interactive React components within your Markdown content" — Nextra vs Docusaurus

Astro:

  • Default: Markdown (.md)
  • Optional: MDX via @astrojs/mdx integration
  • Philosophy: Content-first, framework-agnostic
  • Flexibility: Choose markdown or MDX per page

"Astro's docs theme uses Markdown (.md) files by default and does not require you to use MDX, though MDX integration is optionally available and included in the Starlight theme by default" — Astro MDX Guide

VitePress (Vue Ecosystem):

  • Default: Markdown with Vue components in frontmatter
  • NO MDX: Vue-powered, not React
  • Philosophy: Markdown-first, Vue enhancement
  • Users: Vite docs, Vue docs, Vitest

"VitePress is a Vue-powered static site generator built on top of the Vite build tool, providing a Markdown-first workflow with Vue components" — Choosing Documentation Site

Gatsby:

  • Plugin: gatsby-plugin-mdx
  • Support: Both markdown and MDX
  • GraphQL: Query frontmatter via GraphQL layer
  • Users: React docs (legacy), Apollo docs

Industry Adoption Patterns​

MDX Adopters:

  • Companies: Vercel, GitHub, Facebook, Netflix, Stripe
  • Use Cases: Technical documentation, developer blogs, component showcases
  • Rationale: Interactive demos, reusable components, type safety

Markdown Adopters:

  • Use Cases: Content-heavy blogs, non-technical documentation, CMS-driven sites
  • Rationale: Simplicity, portability, non-technical contributors

Hybrid Approach:

  • Astro, Gatsby, Hugo (via shortcodes)
  • Markdown for most content, MDX for special interactive pages
  • Best of both worlds

"Companies like Vercel, GitHub, Facebook, and Netflix have standardized on MDX for their documentation and technical blogs" — MDX vs Markdown Comparison

MDX Growth:

  • v3 release (2024): Improved performance, better TypeScript support
  • Increasing adoption in component libraries (Radix, shadcn/ui docs)
  • Education platforms embracing interactive tutorials

Markdown Resilience:

  • Still dominant for blogs, wikis, general content
  • Obsidian, Notion, Linear use markdown (not MDX)
  • Markdown remains interchange format (Pandoc, etc.)

Security Considerations​

MDX Security Model​

Execution Risk:

"MDX's ability to execute JSX introduces different attack vectors that require careful implementation of security guards" — Markdown XSS Guide

Attack Vectors:

  1. Malicious component imports: import {Malware} from 'user-supplied-package'
  2. XSS via props: Unsanitized user input passed to components
  3. Code injection: If MDX source is user-generated (CMS scenarios)

CVE Example:

"CVE-2025-24981 in the Nuxt MDC library, where unsafe parsing logic of URL text extracted from markdown content can lead to arbitrary JavaScript code due to a bypass to existing guards around the javascript: protocol scheme" — Nuxt MDC XSS

Mitigation:

  • ✅ Only compile MDX from trusted sources
  • ✅ Sanitize props from user input
  • ✅ Use Content Security Policy (CSP) headers
  • ✅ Regularly audit dependencies
  • ❌ NEVER compile user-submitted MDX at runtime

Runtime Markdown Security Model​

Default Safety:

"React Markdown avoids raw HTML injection by safely converting Markdown into structured React elements, and by default is safe because it does not render raw HTML, which helps protect applications from cross-site scripting vulnerabilities" — React Markdown Security

HTML Handling:

// Unsafe: renders raw HTML
<ReactMarkdown skipHtml={false}>
  {userInput}  // DANGER: XSS risk
</ReactMarkdown>

// Safe: strips HTML by default
<ReactMarkdown>
  {userInput}  // Safe: HTML tags removed
</ReactMarkdown>

Link Safety:

<ReactMarkdown
  urlTransform={(url) => {
    // Block javascript: protocol
    if (url.startsWith('javascript:')) return ''
    // Sanitize external URLs
    return sanitizeUrl(url)
  }}
>
  {userContent}
</ReactMarkdown>

Comparison:

AspectMDXRuntime Markdown
Default PostureTrusts sourceDistrusts source
HTML InjectionPossible via JSXBlocked by default
XSS RiskHigh if user-generatedLow with proper config
Best ForTrusted authorsUser-generated content

Decision Matrix​

Choose MDX When:​

✅ Interactive documentation requiring live demos ✅ Component showcases (design systems, UI libraries) ✅ Developer-authored content with technical expertise ✅ Type-safe content with TypeScript integration ✅ Large content volume (100+ pages) for bundle size benefits ✅ Reusable components needed across many pages ✅ Build-time optimization is critical for performance

Choose Runtime Markdown When:​

✅ Non-technical authors contributing content ✅ CMS-driven content from external systems ✅ User-generated content requiring sandboxing ✅ Content portability across platforms (export to PDF, email, etc.) ✅ Small content volume (<10 pages) ✅ Simple formatting without interactive needs ✅ Security-first posture for untrusted sources

Hybrid Approach:​

✅ Default to markdown for most content ✅ Use MDX selectively for interactive pages (landing, tutorials, demos) ✅ Separate directories: content/articles/*.md + content/interactive/*.mdx ✅ Shared components for both markdown (via component mapping) and MDX

Performance Benchmarks Summary​

MetricMDXRuntime Markdown
Build TimeCompile all files (~5s for 100 files)No build step
Runtime Parse0 ms (pre-compiled)~10-50 ms per file
First LoadInstant (static HTML)Parse on mount
Bundle Size (100 files)~500 KB (compiled)~15 KB parser + ~200 KB content
HMR Speed10-20 msN/A
Search IndexBuild-time extractionRuntime parsing

Code Example: Side-by-Side Comparison​

Same Content - Different Approaches​

MDX Version (article.mdx):

---
title: "React Performance Guide"
author: "Jane Developer"
publishedAt: "2026-02-14"
---

import { PerformanceChart } from '@/components/PerformanceChart'
import { CodeSandbox } from '@/components/CodeSandbox'
import { useState } from 'react'

export const InteractiveDemo = () => {
  const [count, setCount] = useState(0)
  return (
    <div>
      <button onClick={() => setCount(count + 1)}>
        Render count: {count}
      </button>
      <p>This component re-renders on every click!</p>
    </div>
  )
}

# {title}

By {author} • {publishedAt}

## Performance Metrics

<PerformanceChart data={performanceData} />

## Try It Yourself

<InteractiveDemo />

## Live Sandbox

<CodeSandbox
  template="react"
  files={{
    'App.js': `
      import React, { useState } from 'react'

      export default function App() {
        const [count, setCount] = useState(0)
        return <button onClick={() => setCount(count + 1)}>{count}</button>
      }
    `
  }}
/>

Runtime Markdown Version (article.md + React wrapper):

---
title: "React Performance Guide"
author: "Jane Developer"
publishedAt: "2026-02-14"
---

# React Performance Guide

By Jane Developer • 2026-02-14

## Performance Metrics

[See chart](#performance-chart)

## Try It Yourself

[Interactive demo not available in markdown]

## Live Sandbox

[Visit CodeSandbox](https://codesandbox.io/s/react-demo)
// ArticlePage.jsx
import ReactMarkdown from 'react-markdown'
import matter from 'gray-matter'
import { PerformanceChart } from '@/components/PerformanceChart'

function ArticlePage({ source }) {
  const { data: frontmatter, content } = matter(source)

  return (
    <article>
      <h1>{frontmatter.title}</h1>
      <p className="meta">
        By {frontmatter.author} • {frontmatter.publishedAt}
      </p>

      <ReactMarkdown
        components={{
          a: ({href, children}) => {
            // Replace chart link with component
            if (href === '#performance-chart') {
              return <PerformanceChart data={performanceData} />
            }
            return <a href={href}>{children}</a>
          }
        }}
      >
        {content}
      </ReactMarkdown>
    </article>
  )
}

Key Differences:

  • MDX: Components embedded inline, full interactivity
  • Markdown: Components injected via links or custom renderer logic
  • MDX: Single file contains content + logic
  • Markdown: Separation of content (markdown) and behavior (React wrapper)

Conclusion​

MDX is optimized for:

  • Developer-centric documentation
  • Interactive technical content
  • Component-driven architectures
  • Build-time performance at scale

Runtime Markdown is optimized for:

  • Content-first workflows
  • Non-technical authoring
  • Security-sensitive scenarios
  • Portability and simplicity

The optimal choice depends on:

  1. Authoring team: Developers vs. content writers
  2. Interactivity needs: Static formatting vs. dynamic components
  3. Security requirements: Trusted sources vs. user-generated content
  4. Content volume: Small sites vs. large documentation portals
  5. Performance priorities: Build-time vs. runtime optimization

Recommendation: Start with runtime markdown for simplicity. Migrate to MDX only when you have clear requirements for embedded interactivity that cannot be achieved through component mapping or page-level composition.

Sources​