Guide · Open source
How to use MDX: write JSX components inside Markdown
Updated · written with AI from the project's own documentation and checked against our catalogue data
MDX is an open-source format that lets you write JSX components directly inside Markdown documents. This guide explains what it does, shows the basic file structure, and walks through the setup path the project points to. By the end, you will know whether MDX fits a documentation or content site you are building with React, Preact, or Vue.
MDXmdx-js/mdx · ★ 19.8k · MIT Install options & downloads Quick start
- 1Confirm Node.js is installed. MDX's listed prerequisite is Node.js, so make sure it is available on your machine before continuing.
- 2Open the Getting started guide. The README sends you to the Getting started page on mdxjs.com for how to integrate MDX into a project.
- 3Choose your bundler and framework. Pick the integration that matches your build tool, such as webpack or Rollup, and your UI framework, such as React, Preact, or Vue.
- 4Install the MDX packages. Add the packages through your package manager by following the official integration steps for your setup.
- 5Write an MDX file. Create a file that mixes Markdown text with imports, exports and JSX components, following the example in the README.
- 6Test in the Playground. Use the MDX Playground on mdxjs.com to check how your syntax renders before relying on it in your build.
What MDX is and what it does
MDX is an authorable format that lets you write JSX in your Markdown documents. You can import components, such as interactive charts or alerts, and place them within your text.
The project's own example imports a Chart component, defines a year value, and then uses both the value and the component inside ordinary Markdown prose.
import {Chart} from './snowfall.js'
export const year = 2013
# Last year’s snowfall
In {year}, the snowfall was above average.
It was followed by a warm spring which caused
flood conditions in many of the nearby rivers.
<Chart year={year} color="#fcb32c" />Understand the parts of an MDX file
An MDX file mixes three kinds of content. Markdown handles headings and text, import and export statements bring in components and values, and JSX tags such as <Chart /> render components in place. Curly braces like {year} insert a JavaScript value into the text.
The README's example is the best reference for this structure: the imports and exports sit at the top, the prose follows, and the component is placed where it should appear.
- import pulls a component from another file, such as ./snowfall.js
- export const defines a value you can reuse in the document
- {year} inserts that value into a sentence
- <Chart year={year} color="#fcb32c" /> renders the component with props
Install MDX with a package manager
The project is installed as packages through a package manager, and its prerequisite listed in this analysis is Node.js. The README does not list specific install commands, so follow the Getting started guide on the project website for the exact packages and setup for your project.
Because setup requires build tooling, plan to add MDX to a project that already compiles JavaScript.
- Install Node.js first
- Follow the Getting started guide at mdxjs.com for integration steps
- Pick the integration that matches your bundler, such as webpack or Rollup, and your framework, such as React, Preact, or Vue
Try MDX in the browser before you install it
The project provides a Playground on its website where you can test MDX without setting up a project. The README also links to a page titled What is MDX for background on the format.
Using the Playground first is a low-cost way to see how your components will behave in MDX before you wire up a build.
Check whether MDX fits your project
MDX suits teams building documentation or content sites in React, Preact, or Vue, especially when they already use webpack, Rollup, or similar bundlers. It is aimed at people comfortable with JavaScript and JSX syntax.
It is a poor fit for plain Markdown needs. MDX adds JSX syntax that plain Markdown renderers will not understand, so content written in it cannot be dropped into a tool that only reads standard Markdown.
- Good fit: long-form content that needs interactive components
- Good fit: projects already built with JavaScript bundlers
- Poor fit: writers who only need plain Markdown
- Poor fit: non-developers without JavaScript experience
Get help, report security issues and contribute
The README points to a Security page on the project website, a Contribute page with ways to get started, and a Support page for getting help. The project also has a code of conduct that applies to anyone interacting with the repository or community.
Discussions on the GitHub repository are linked as the chat channel.
What people use it for
- Documentation sites in React, Preact, or Vue that embed interactive examples
- Long-form articles that include charts or alerts imported from component files
- Content sites built on bundlers like webpack or Rollup that need components alongside prose
Frequently asked questions
Is MDX free to use?
Yes. The repository is licensed under MIT, which the README states, and the project is open source. Check the license file in the repository for the full terms.
What do I need to install MDX?
The listed prerequisite is Node.js, and installation is done through a package manager. The README does not give exact install commands, so use the Getting started guide at mdxjs.com.
Can I use MDX without React?
The README says MDX works with frameworks such as React, Preact, and Vue. Projects not using a JavaScript-based framework are not a good fit, since the README focuses on those three.
What is the difference between MDX and Markdown?
MDX lets you write JSX components inside Markdown, while plain Markdown renderers do not understand JSX. If you only need standard Markdown, MDX adds complexity you do not need.
Does MDX work with webpack and Rollup?
Yes. The README says the repository includes packages for integrating with bundlers such as webpack and Rollup.
Where can I get help with MDX?
The README links to a Support page on mdxjs.com and to GitHub discussions as the chat channel. Security questions are covered on the Security page of the website.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
MDX is a good choice for developers building documentation or content sites in React, Preact, or Vue who want interactive components inside long-form writing. If you only need plain Markdown, or you are not comfortable with JavaScript and build tooling, pick a standard Markdown tool instead.
Install options & downloads