# MDX — Markdown for the Component Era

> MDX lets you use JSX components directly inside Markdown documents, enabling interactive and dynamic content in documentation sites, blogs, and design systems.

## Install

Save in your project root:

# MDX — Markdown for the Component Era

## Quick Use
```bash
# Install core packages
npm install @mdx-js/mdx @mdx-js/react

# With Next.js
npm install @next/mdx @mdx-js/loader

# Write an MDX file (example.mdx):
# import { Chart } from './Chart'
# # Hello World
# <Chart data={[1,2,3]} />

# MDX compiles to a React component automatically
```

## Introduction
MDX is an authoring format that combines the simplicity of Markdown with the power of JSX. It allows you to import and render React (or other framework) components directly within Markdown content, making it the standard for interactive documentation, blogs, and content-heavy applications.

## What MDX Does
- Parses Markdown with embedded JSX expressions and component imports
- Compiles MDX files into framework components (React, Preact, Vue, Svelte)
- Supports standard Markdown syntax including GFM (tables, task lists, footnotes)
- Allows passing props and data to embedded components at render time
- Integrates with remark and rehype plugin ecosystems for content transformation

## Architecture Overview
MDX uses a pipeline: the MDX compiler parses source into an AST using micromark (Markdown) and acorn (JavaScript), then applies remark/rehype plugins for transformations, and finally serializes the AST into a JavaScript module that exports a component function. This pipeline runs at build time, producing static or server-rendered output with no client runtime cost for static content.

## Self-Hosting & Configuration
- Add `@mdx-js/loader` to webpack or use the Vite plugin `@mdx-js/rollup`
- Configure via `mdx` options in your bundler (remarkPlugins, rehypePlugins)
- Use `next.config.mjs` with `@next/mdx` for Next.js integration
- Set `providerImportSource` to customize the component provider
- Add TypeScript types with `@types/mdx` for editor autocompletion

## Key Features
- Full interop with any component framework via JSX
- remark/rehype plugin system for syntax extensions and transformations
- Compiles to static output with zero client JS for non-interactive content
- Supports expressions, imports, and exports inside Markdown
- Works with content layers like Contentlayer, Velite, or Fumadocs

## Comparison with Similar Tools
- **Markdoc** — Stripe's Markdoc uses custom tag syntax; MDX uses standard JSX familiar to React developers
- **Astro Components** — Astro's `.astro` files mix HTML and JS; MDX focuses specifically on Markdown-first content
- **remark-html** — remark outputs static HTML; MDX produces interactive component trees
- **Docusaurus Markdown** — Docusaurus uses MDX under the hood for its documentation features
- **reStructuredText** — RST is powerful but Python-ecosystem-only; MDX works across JS frameworks

## FAQ
**Q: Does MDX add runtime overhead?**
A: No. MDX compiles at build time. Static content ships as plain HTML with zero additional JavaScript.

**Q: Can I use MDX with Vue or Svelte?**
A: Yes. MDX v3 supports multiple JSX runtimes. Configure the `jsxImportSource` option for your framework.

**Q: How do I add syntax highlighting to code blocks?**
A: Use rehype plugins like `rehype-shiki` or `rehype-prism-plus` in your MDX pipeline configuration.

**Q: Is MDX compatible with standard Markdown files?**
A: Yes. Any valid Markdown file is valid MDX. You can rename `.md` to `.mdx` and add components incrementally.

## Sources
- https://github.com/mdx-js/mdx
- https://mdxjs.com

---
Source: https://tokrepo.com/en/workflows/asset-08b5e23d
Author: AI Open Source