MDX and React

Docusaurus supports MDX, which means you can write React JSX directly inside Markdown files. This allows you to create interactive documentation, reusable UI elements, and advanced layouts—without leaving your Markdown workflow.

Quick Debugging

The MDX compiler is strict. If you hit errors, try the MDX Playground to validate your syntax.

Exporting Components

You can define a React component inside an MDX file by exporting it. Lines starting with export are treated as code, not prose:

export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      color: '#fff',
      borderRadius: '4px',
      padding: '0.2rem',
    }}>
    {children}
  </span>
);

<Highlight color="#25c2a0">Docusaurus Green</Highlight> is my favorite color!

http://localhost:3000

Docusaurus Green is my favorite color!

JSX vs HTML

All MDX files are parsed as JSX. Inline styles use JS objects:

/* Incorrect HTML style */
<span style="background-color:red">Foo</span>
/* Correct JSX style */
<span style={{backgroundColor:'red'}}>Foo</span>

Importing Components

Instead of defining components inline, you can import them:

import BrowserWindow from '@site/src/components/BrowserWindow';
import Button from '@mui/material/Button';

The @site alias points to the root of your Docusaurus site. This makes imports stable even when docs are versioned or moved.

http://localhost:3000

Imported Component Example

If a component is complex or reused across many pages, keep it in a .js file:

src/components/Highlight.js

import React from 'react';

export default function Highlight({children, color}) {
  return <span style={{backgroundColor: color, color: '#fff'}}>{children}</span>;
}

docs/my-page.mdx

import Highlight from '@site/src/components/Highlight';

<Highlight color="#25c2a0">Reusable Component</Highlight>

http://localhost:3000

Reusable Component

Global Components

You can register components globally so they’re available everywhere without imports. Wrap the default MDX mapping:

src/theme/MDXComponents.js

import React from 'react';
import MDXComponents from '@theme-original/MDXComponents';
import Highlight from '@site/src/components/Highlight';

export default {
  ...MDXComponents,
  Highlight,
};

Now <Highlight> works in any MDX file:

Use <Highlight color="#25c2a0">Docusaurus Green</Highlight> globally!

Uppercase Required

MDX v3 treats lowercase tags as HTML elements. Always use UpperCamelCase for custom components.

Using Markdown Partials

You can import other Markdown files as components. Files prefixed with _ won’t create a standalone page:

_snippet.mdx

This is a reusable snippet for <b>{props.name}</b>.

import Snippet from './_snippet.mdx';

<Snippet name="Ajay" />

This lets you reuse content across multiple pages.

Importing Code as Raw Text

You can display raw code from an external file using Webpack’s raw-loader:

npm install --save raw-loader

import CodeBlock from '@theme/CodeBlock';
import MySource from '!!raw-loader!./MyComponent';

<CodeBlock language="jsx">{MySource}</CodeBlock>

This is perfect for live examples that stay synced with actual code.

Available Globals

Inside an MDX page, you can access:

• frontMatter – metadata from the file’s YAML front matter.
• toc – table of contents headings as a JSON tree.
• contentTitle – first h1 heading in the file.

import CodeBlock from '@theme/CodeBlock';

<CodeBlock className="language-json">
{JSON.stringify({frontMatter, toc, contentTitle}, null, 2)}
</CodeBlock>

http://localhost:3000

Front matter, TOC, and content title are accessible as globals!

---

With MDX, Docusaurus turns Markdown into a React-powered playground. Mix documentation with live components, code examples, and dynamic UI— all in one seamless authoring experience.