#MDX and React components

Rspress supports MDX, 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 provided by Rspress.

# Hello, world!

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

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

#MDX 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:

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

Testing the use of MDX fragments and React components.

<MdxFragment />

<TsxComponent />

This is **mdx fragment**.

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:

In .mdx files, you can use the built-in components provided by Rspress or install React component libraries to enrich your documentation.

#Routing convention

In the docs directory, MDX fragments or React components must be excluded from routing with route.exclude. For convenience, files starting with "_" are excluded by default through route.excludeConvention.

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

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

<ButtonFragment />
<Button />

#### button

This is text from MDX

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

It is rendered as:

#Escape Hatch: writing document content in 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:

#React version requirements