#MDX and React components

Rspress supports MDX, a content authoring format that seamlessly combines Markdown with JSX. MDX allows you to use React components directly in your documentation, combining Markdown's concise syntax with the power of the React ecosystem, making it ideal for building interactive, component-based technical documentation.

#What is MDX

MDX is a combination of Markdown and JSX syntax, allowing you to write and use React components directly in Markdown documents.

We recommend using .mdx for all documentation files, which enables you to write content just like regular Markdown and also import and utilize 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 will be rendered as:

You can use built-in components provided by Rspress or install some React component libraries to enrich your documentation in .mdx files.

#Routing convention

In the docs directory, MDX fragments or React components need to be excluded from routing through the route.exclude configuration. For convenience, files starting with "_" are excluded by default via 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 will be 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 will be rendered as:

#React version requirements