> For AI agents: the complete documentation index is available at https://rspress.rs/llms.txt, the full documentation bundle is available at https://rspress.rs/llms-full.txt.

# MDX and React components

Rspress supports [MDX](https://mdxjs.com/), a content authoring format that seamlessly combines Markdown with JSX. MDX lets you use React components directly in your documentation, pairing Markdown's concise syntax with the React ecosystem. It is ideal for building interactive, component-based technical documentation.

## What is MDX

MDX combines Markdown and JSX syntax, so you can write Markdown content and use React components in the same file.

We recommend using `.mdx` for all documentation files. This lets you write content like regular Markdown while importing and using the [built-in components](https://rspress.rs/ui/components/index.md) provided by Rspress.

```mdx title="docs/index.mdx"
# Hello, world!

import { PackageManagerTabs } from '@rspress/core/theme';

<PackageManagerTabs command="create rspress@latest" />
```

## MDX fragments \{#fragments}

In MDX, every `.mdx` file is compiled into a React component, which means it can be imported like any component and can freely render React components. For example:


**docs/index.mdx**

```mdx
import MdxFragment from './_mdx-fragment.mdx';
import TsxComponent from './_tsx-component';

Testing the use of MDX fragments and React components.

<MdxFragment />

<TsxComponent />
```


**docs/_mdx-fragment.mdx**

```mdx file="./_mdx-fragment.mdx"
This is **mdx fragment**.

```


**docs/_tsx-component.tsx**

```tsx file="./_tsx-component.tsx"
import { useState } from 'react';

export default () => {
  const [count, setCount] = useState(0);
  return (
    <p>
      This is a component from tsx{' '}
      <button onClick={() => setCount(count => count + 1)}>{count}</button>
    </p>
  );
};

```


It renders as:


Testing the use of MDX fragments and React components.
This is **mdx fragment**.

This is a component from tsx 0


In `.mdx` files, you can use the [built-in components](https://rspress.rs/ui/components/index.md) provided by Rspress or install React component libraries to enrich your documentation.

## Routing convention

In the [docs directory](https://rspress.rs/api/config/config-basic.md#root), MDX fragments or React components must be excluded from routing with [route.exclude](https://rspress.rs/api/config/config-basic.md#routeexclude). For convenience, files starting with "\_" are excluded by default through [route.excludeConvention](https://rspress.rs/api/config/config-basic.md#routeexcludeconvention).

You can also place components in adjacent directories outside the docs directory. For example:

```tree
docs
├── _button.mdx
└── index.mdx
components
└── button.tsx
```


**docs/index.mdx**

```mdx
import ButtonFragment from './_button.mdx';
import Button from '../../components/button';

<ButtonFragment />
<Button />
```


**docs/_button.mdx**

```mdx file="./_button.mdx"
#### button

This is text from MDX

```


**components/button.tsx**

```tsx
const Button = () => <button>This is a button from tsx</button>;
export default Button;
```


It is rendered as:


#### button

This is text from MDX
This is a button from tsx

## Escape Hatch: writing document content in tsx

```tsx file="./_escape-hatch.tsx" title="_escape-hatch.tsx"
import { getCustomMDXComponent } from '@rspress/core/theme';

export default () => {
  const { p: P, code: Code } = getCustomMDXComponent();
  return (
    <P className="rp-doc">
      This is content in tsx, but the styles are the same as in the
      documentation, such as <Code>@rspress/core</Code>. However, this text with
      className="rp-not-doc"
      <Code className="rp-not-doc">@rspress/core</Code> will not take effect
    </P>
  );
};

```

It renders as:


This is content in tsx, but the styles are the same as in the documentation, such as `@rspress/core`. However, this text with className="rp-not-doc"`@rspress/core` will not take effect


:::warning

TSX and HTML syntax can make it difficult to extract static information, such as local search indexes.

We recommend using `.mdx` files for document content and `.tsx` files for interactive dynamic content.

:::

## React version requirements

| Dependency         | Allowed Range          | Default Version | Notes                                     |
| ------------------ | ---------------------- | --------------- | ----------------------------------------- |
| `react`            | `^18.0.0 \|\| ^19.0.0` | 19              | React 17 is no longer supported           |
| `react-dom`        | `^18.0.0 \|\| ^19.0.0` | 19              | Keep consistent with react version        |
| `react-router-dom` | `^6.0.0 \|\| ^7.0.0`   | 7               | Uses project version if already installed |

:::tip

If `react`, `react-dom`, or `react-router-dom` is already installed in your project, Rspress will prioritize using the version installed in your project rather than the built-in default version.

:::