MDX and 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.

note

While both .md and .mdx files are parsed using MDX, some of the syntax are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the .mdx extension for files containing MDX syntax.

caution

MDX is not 100% compatible with CommonMark.

Use the MDX playground to ensure that your syntax is valid MDX.

Try this block here:

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:

http://localhost:3000

Docusaurus green and Facebook blue are my favorite colors.

I can write Markdown alongside my JSX!

You can also import your own components defined in other files or third-party components installed via npm! Check out the MDX docs to see what other fancy stuff you can do with MDX.

caution

Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects. This behavior is different from Docusaurus 1. See also Migrating from v1 to v2.

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, first you need to install it in your project:

npm

npm install --save raw-loader

Yarn

yarn add raw-loader

Now you can import code snippets from another file as it is:

myMarkdownFile.mdx

import CodeBlock from '@theme/CodeBlock';
import MyComponentSource from '!!raw-loader!./myComponent';

<CodeBlock className="language-jsx">{MyComponentSource}</CodeBlock>

http://localhost:3000

/**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */

import React, {useState} from 'react';

export default function MyComponent() {
  const [bool, setBool] = useState(false);
  return (
    <div>
      <p>MyComponent rendered !</p>
      <p>bool={bool ? 'true' : 'false'}</p>
      <p>
        <button onClick={() => setBool((b) => !b)}>toggle bool</button>
      </p>
    </div>
  );
}

You can also pass title prop to CodeBlock component in order to appear it as header above your codeblock:

<CodeBlock className="language-jsx" title="/src/myComponent">
  {MyComponentSource}
</CodeBlock>

note

You have to use <CodeBlock> rather than the Markdown triple-backtick ```, because the latter will ship out any of its content as-is, but you want JSX to insert the imported text here.

warning

This feature is experimental and might be subject to API breaking changes in the future.

Importing Markdown

You can use Markdown files as components and import them elsewhere, either in Markdown files or in React pages.

By convention, using the _ filename prefix will not create any doc page and means the markdown file is a "partial", to be imported by other files.

_markdown-partial-example.mdx

<span>Hello {props.name}</span>

This is text some content from `_markdown-partial-example.mdx`.

someOtherDoc.mdx

import PartialExample from './_markdown-partial-example.mdx';

<PartialExample name="Sebastien" />;

http://localhost:3000

Hello Sebastien

This is text some content from _markdown-partial-example.md.

This way, you can reuse contents among multiple pages and avoid duplicating materials.

caution

The table-of-contents does not currently contain the imported Markdown headings. This is a technical limitation that we are trying to solve (issue).