MDX e React
Using JSX in Markdown
Docusaurus has built-in support for MDX v1, which allows you to write JSX within your Markdown files and render them as React components.
While Docusaurus parses both .md
and .mdx
files using MDX, some of the syntaxes are treated slightly differently by third-party tools. For the most accurate parsing and better editor support, we recommend using the .mdx
extension for files containing MDX syntax.
Check out the MDX docs to see what other fancy stuff you can do with MDX.
Exporting components
To define any custom component within an MDX file, you have to export it: only paragraphs that start with export
will be parsed as components instead of prose.
export const Highlight = ({children, color}) => (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
I can write **Markdown** alongside my _JSX_!
Notice how it renders both the markup from your React component and the Markdown syntax:
I can write Markdown alongside my JSX!
Since all doc files are parsed using MDX, anything that looks like HTML is actually JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects.
/* Instead of this: */
<span style="background-color: red">Foo</span>
/* Use this: */
<span style={{backgroundColor: 'red'}}>Foo</span>
This behavior is different from Docusaurus 1. See also Migrating from v1 to v2.
In addition, MDX is not 100% compatible with CommonMark. Use the MDX playground to ensure that your syntax is valid MDX.
Importing components
You can also import your own components defined in other files or third-party components installed via npm.
<!-- Docusaurus theme component -->
import TOCInline from '@theme/TOCInline';
<!-- External component -->
import Button from '@mui/material/Button';
<!-- Custom component -->
import BrowserWindow from '@site/src/components/BrowserWindow';
The @site
alias points to your website's directory, usually where the docusaurus.config.js
file is. Using an alias instead of relative paths ('../../src/components/BrowserWindow'
) saves you from updating import paths when moving files around, or when versioning docs and translating.
While declaring components within Markdown is very convenient for simple cases, it becomes hard to maintain because of limited editor support, risks of parsing errors, and low reusability. Use a separate .js
file when your component involves complex JS logic:
import React from 'react';
export default function Highlight({children, color}) {
return (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
}
import Highlight from '@site/src/components/Highlight';
<Highlight color="#25c2a0">Docusaurus green</Highlight>
If you use the same component across a lot of files, you don't need to import it everywhere—consider adding it to the global scope. See below
MDX component scope
Apart from importing a component and exporting a component, a third way to use a component in MDX is to register it to the global scope, which will make it automatically available in every MDX file, without any import statements.
For example, given this MDX file:
- a
- list!
And some <Highlight>custom markup</Highlight>...
It will be compiled to a React component containing ul
, li
, p
, and Highlight
elements. Highlight
is not a native html element: you need to provide your own React component implementation for it.
In Docusaurus, the MDX component scope is provided by the @theme/MDXComponents
file. It's not a React component, per se, unlike most other exports under the @theme/
alias: it is a record from tag names like Highlight
to their React component implementations.
If you swizzle this component, you will find all tags that have been implemented, and you can further customize our implementation by swizzling the respective sub-component, like @theme/MDXComponents/Code
(which is used to render Markdown code blocks).
If you want to register extra tag names (like the <Highlight>
tag above), you should consider wrapping @theme/MDXComponents
, so you don't have to maintain all the existing mappings. Since the swizzle CLI doesn't allow wrapping non-component files yet, you should manually create the wrapper:
import React from 'react';
// Import the original mapper
import MDXComponents from '@theme-original/MDXComponents';
import Highlight from '@site/src/components/Highlight';
export default {
// Re-use the default mapping
...MDXComponents,
// Map the "<Highlight>" tag to our Highlight component
// `Highlight` will receive all props that were passed to `<Highlight>` in MDX
Highlight,
};
And now, you can freely use <Highlight>
in every page, without writing the import statement:
I can conveniently use <Highlight color="#25c2a0">Docusaurus green</Highlight> everywhere!
I can conveniently use Docusaurus green everywhere!
We use upper-case tag names like Highlight
on purpose.
From MDX v2+ onward (Docusaurus v3+), lower-case tag names are always rendered as native html elements, and will not use any component mapping you provide.
This feature is powered by a wrapper provider. If you are importing Markdown in a React page, you have to supply this provider yourself through the MDXContent
theme component.
import React from 'react';
import FeatureDisplay from './_featureDisplay.mdx';
import MDXContent from '@theme/MDXContent';
export default function LandingPage() {
return (
<div>
<MDXContent>
<FeatureDisplay />
</MDXContent>
</div>
);
}
If you don't wrap your imported MDX with MDXContent
, the global scope will not be available.
Markdown and JSX interoperability
Docusaurus v2 is using MDX v1, which has a lot of known cases where the content fails to be correctly parsed as Markdown. Use the MDX playground to ensure that your syntax is valid MDX.
Samples of parsing failures
A paragraph starting with a JSX tag will be seen entirely as a JSX string:
- Problem
- Workaround
<span style={{color: 'red'}}>Highlighted text</span> but afterwards _Markdown_ **doesn't work**
Highlighted text but afterwards Markdown doesn't work
Use JSX for the rest of the line, or prefix the line with some plain text:
<span style={{color: 'red'}}>Use JSX for the paragraph</span> to stop <i>worrying about</i> <b>Markdown</b>
​<span style={{color: 'red'}}>← This is a zero-width space</span> and afterwards <i>Markdown</i> <b>works</b>
Use JSX for the paragraph to stop worrying about Markdown
← This is a zero-width space and afterwards Markdown works
Markdown within a JSX tag never works:
- Problem
- Workaround
<span style={{color: 'red'}}>**Bold doesn't work**</span>
Use JSX within JSX tag, or move the Markdown to the outer layer:
<span style={{color: 'red'}}><b>Bold now works</b></span>
**<span style={{color: 'red'}}>Bold now works</span>**
Bold now works
Text immediately below a JSX tag will be seen as JSX text:
- Problem
- Workaround
<div style={{color: 'red'}}>
**Bold still doesn't work**
</div>
Bold still doesn't work
Add an empty new line:
<div style={{color: 'red'}}>
**Bold now works**
</div>
Bold now works
Markdown text indented by four spaces will be seen as a code block:
- Problem
- Workaround
<div style={{color: 'red'}}>
You may think I'm just some text...
</div>
You may think I'm just some text...
Don't indent:
<div style={{color: 'red'}}>
Now I'm actually just text
</div>
Now I'm actually just text
Importing code snippets
You can not only import a file containing a component definition, but also import any code file as raw text, and then insert it in a code block, thanks to Webpack raw-loader. In order to use raw-loader
, you first need to install it in your project:
- npm
- Yarn
- pnpm
npm install --save raw-loader
yarn add raw-loader
pnpm add raw-loader