Using React

Using JSX in Markdown

Docusaurus has built-in support for MDX, 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.

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.

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>  );}

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. Below we are importing from another file and inserting it as a component.

import Intro from './markdown-features-intro.mdx';
<Intro />;

http://localhost:3000

Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible.

Docusaurus 2 uses modern tooling to help you compose your interactive documentations with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.

In this section, we'd like to introduce you to the tools we've picked that we believe will help you build a powerful documentation. Let us walk you through with an example.

Markdown is a syntax that enables you to write formatted content in a readable syntax.

The standard Markdown syntax is supported, and we use MDX as the parsing engine, which can do much more than just parsing Markdown, like rendering React components inside your documents.

important

This section assumes you are using the official Docusaurus content plugins.

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).